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This Book 



The Advanced Programmer ' s Guide is intended for programmers who axe 
experienced with 50 Series™ systems, developed by Prime, and at least 
one high-level language supplied by Prime (preferably PL/I or FORTRAN 
77). Readers should have read the Prime User's Guide , D0C4130-5IA, and 
the Programmer's Guide to BIND and EPFs , D0C8691-1IA. Familiarity with 
the Subroutines Reference Guides Volumes I-IV, IDC10080-2IA, 
D0C10081-1IA through D0C10083-1LA, and updates UPD10081-11A through 
UPD10083-11A will be helpful. Prime system architecture is described 
in the Prime 50 Series Technical Summary , E0069C4-2LA, and in the 
System Architecture Reference Guide , D0C9473-2IA. 

The following books are also referenced in this volume: System 
Administrator's Guide , Vol III: System Access and Security, 
D0C10133-1LA; Security Features User's Guide , D0C10130-1LA; PRIMPS 
Commands Reference Guide , D0C3108-6LA. 

This guide consists of four volumes. At PRIMOS® Rev. 21.0, the set 
consists of the following editions: 

Advanced Programmer's Guide, Volume 0, Introduction and Error 
Codes, D0C10066-1IA and update UPD10066-11A 

Advanced Programmer's Guide, Volume I, BIND and EPFs, D0C10055-1LA 

Advanced Programmer's Guide, Volume II, File System, D0C10056-2LA 

Advanced Programmer's Guide, Volume III, Command Environment, 
D0C10057-1IA 
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Information is divided among the set as follows: 

• Executable Program Formats (EPFs) in Volume I 

• The PRIMOS File System in Volume II 

• The PRIMOS Command Environment in Volume III 

• New features for readers of this guide in Volume 

• Standard error codes used by PRIMOS, along with their messages 
and meanings, in Volume 

Volume also contains information . applicable to all of the other 
volumes, such as an explanation of the presentation of the subroutine 
calls, general coding guidelines, and the like. 

Designed for systems-level programmers, this guide describes the 
lowest-level interfaces supported by PRIMOS and its utilities. 
Higher-level interfaces not described in this guide include: 

• Language-directed I/O 

• The applications library (APPLIB) 

• The sort packages (VSRTLI and MSORTS) 

• Data management packages (such as MPLUSLB and PRISAMT.TB) 

• Other subroutine packages 

All of these higher-level interfaces are described in other manuals, 
such as language reference manuals, and the four volumes of the 
Subroutines Reference Guide . 

This guide documents the low-level interfaces for use by programmers 
and engineers who are designing new products such as language 
compilers, data management software, electronic mall subsystems, 
utility packages, and so on. Such products are themselves higher-level 
interfaces, typically used by other products rather than by end users, 
and therefore must use some or all of the low-level interfaces 
described in this guide for best results. 

Because of the technical content of the subjects presented in this 
guide, it is expected that this guide will be regularly used only by 
project leaders, design engineers, and technical supervisors rather 
than by all programmers on a project. Most of the information in this 
guide deals with interfaces to PRIMOS that are typically used only in 
small portions of a product, and with overall product design issues 
that should be considered before coding begins. Once the product is 
designed and the PRIMOS interfaces are designed and coded, a typical 
product can then be written by programmers whose knowledge of these 
issues is minimal. Of course, this statement is predicated on the 
assumption that programmers employ widely accepted programming 
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practices such as modular, or structured, programming; functional 
design specifications; and thorough unit debugging and testing. 



and 



PRIME DOCUMENTATION CONVENTIONS 



The following conventions are used in command formats, statement 
formats, and in examples throughout this document. Examples illustrate 
the uses of these commands and statements in typical applications. 
Terminal input may be entered in either uppercase or lowercase letters. 



Convention Explanation 

UPPERCASE In command formats, words 
in uppercase indicate the 
actual names of commands, 
statements, and keywords. 
These can be entered in 
either uppercase or 
lowercase letters. 



Example 
SLIST 



lowercase In command formats, words 

in lowercase letters indicate 
items for which the user must 
substitute a suitable value. 



LOGIN user-id 



Abbreviations 



If a command or statement 
has an abbreviation, it is 
indicated by underlining. 
In cases where the command 
or directive itself 
contains an underscore, the 
abbreviation is shown below 
the full name, and the name 
and abbreviation are placed 
within braces. 



LOGOUT 



SET_QUOTA 
SQ 



underlining 
in 
examples 



Brackets 
[ ] 



Braces 
{ } 



In examples, user input 
is underlined but system 
prompts and output are not. 



Brackets enclose one or 
more optional items. 
Choose none, one, or 
more of these items. 

Braces enclose a list 
of items. Choose one 
and only one of these 
items. 



CK, RESUME MY.PRCG 
This is the output 
of MY_PRCG.CPL 
OK, 



SPOOL 



CLOSE 



-LIST 
-CANCEL 



filename 
ALL 



xizi 



Ellipsis An ellipsis indicates that item-x[ , item-y] . . . 
the preceding item may he 
repeated. 

Parentheses In command or statement DIM array (row, col) 
( ) formats, parentheses must 
he entered exactly 
as shown. 

Hyphen Wherever a hyphen appears SPOOL -LIST 
as the first letter of an 
option, it is a required 
part of that option. 
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PRIMOS File System 

Concepts 



This chapter and Chapter 2, PRCC&AMMER INTERFACES TO THE FILE SYSTEM, 
explain the concepts and -use of the PRIMOS file system. 

What follows in this chapter is a brief description of file systems in 
general, a rationale for their use, and then, in some detail, 
explanations of the elements and concepts that are peculiar to the 
PRIMOS file system. 

Chapter 2 describes in detail the ways in which programmers can use the 
PRIMOS file system elements in building application programs and 
subsystems that create, use, and maintain their own or their company's 
collections of data. 



WHAT IS A FILE SYSTEM? 

It is hard to imagine a large corporation, a small business, or even an 
individual being able to do any business at all without some form of 
data. Something as simple as an address book is one kind of data that 
an individual might use. A checkbook is another. Businesses use data 
in the form of mailing lists, accounts receivable, accounts payable, 
cash on hand, and many other collections of words and numbers in their 
daily transactions. In order to use these words and numbers in any 
efficient and meaningful way, they must be organized in some fashion, 
and there must be tools by which their owners can manipulate them. The 
function of a file system is to provide the organization and the tools 
to store and use information by means of a computer. 
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Data 

The first characteristic of a file system, then, is that it is a 
collection of data — information in the form of letters, digits, and 
symbols arranged into useful groups of words and numbers. If the 
groups are put into some fixed sequence, such as a last name, a first 
name, a middle initial, and a telephone number, each group can be 
called a field . A field is usually designated as either alphanumeric 
(consisting of a mixture of letters, digits, and symbols) or numeric 
(consisting mostly of digits, but possibly including a plus or a minus 
sign, a decimal point, one or more commas, and perhaps a currency 
symbol). Other kinds of fields, such as pure alphabetic or binary, are 
recognized by some programming languages. 

A record is the basic unit upon which most file systems operate. A 
number of fields can be combined into a structured element known as a 
data record . There are also unstructured records, which consist of 
strings of alphanumeric information of varying lengths; these are, 
strictly speaking, also data records, but to distinguish between 
structured and unstructured records, the unstructured records can be 
called text records . As a programmer, you will be using both kinds of 
records: you will write programs in the form of text records; your 
programs will most likely deal with data records. 



Storage 

The second characteristic of a file system is that its data has been 
placed in some kind of storage from which it can be retrieved when 
needed. Many forms of storage exist: punched cards, paper tape, 
magnetic tape, and various forms of magnetic disks. In these chapters 
we will deal only with storage on disks. 



Objects 

Having a collection of data arranged into fields and records and stored 
on a disk is a big step toward organizing the data. It is really all 
that you absolutely need to store and retrieve data. Given a set of 
commands that the computer understands, you could at this point 
successively retrieve records until the desired one is found, and then 
do some kind of operation on it. But this is a tedious task, and there 
might be more than one class of records upon which you want to perform 
different kinds of operations. For example, the telephone number 
records would serve a purpose different from that of, say, accounting 
records, and for reasons of efficiency or privacy, it would be useful 
to keep these two classes of records separate. 

A useful file system should be able to segregate different classes of 
data into different groups, or objects , the most basic of which is the 
file . The previous paragraph hinted at the existence of two files, one 
a list of names and telephone numbers, and the other a list of names 
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aM accounting information. A company employee whose job is to do 
telephone surveys of customers could retrieve their telephone numbers 
from the first file without having to read and skip, or even being able 
to see, any of the information about their accounts in the second file. 

You can also imagine a second level of segregation, in which files, as 
well as records, might be grouped together to serve some particular 
purpose. A company with a nation-wide customer base, for example, 
would maintain account files of all of its customers, but might want to 
operate on them on a state-by-state or regional basis. One approach to 
this task would be to cluster the files for each state or region into 
another kind of object: a catalog containing the names of the files in 
the cluster. These objects serve as directories to the objects 
contained in them, and indeed, some file systems, including the PRIMOS 
file system, call them just that. Directories, along with a suitable 
language, enable identical actions to be performed on several files by 
simply addressing the directory that contains them. 

File systems provide other kinds of objects, whose purposes are to ease 
the burden of dealing with large collections of data, controlling 
access to them, and increasing the efficiency of operating on them. 
What PRIMOS provides will be described later in this chapter. How you 
as a programmer use them will be explained in the next chapter. 



Procedures 

No matter how sophisticated it may be, data organization is only an 
idea, useless without some way to implement it, and then to act on the 
organized data. For these purposes, a set of tools, or procedures , is 
needed. Procedures, written into programs, enable you to create file 
system objects, write data into them, read data from them, control 
access to them, and perform other related functions on both the objects 
themselves and the information contained in them. 



Summary of File System Rationale 

You may have inferred by now that there are good reasons for using a 
file system, no matter how elementary or sophisticated your needs may 
be. File systems come in many forms, with a variety of capabilities 
ranging from simple file creation, reading, and writing to the 
construction of highly complex data bases with hierarchical structures 
and intricate access control mechanisms. But the ultimate goals of any 
file system are simple: to organize data, to enable and simplify 
access to it, and to exercise control over who can do what to it. 

The rest of this chapter explains the elements of the PRIMOS file 
system and how they work together to achieve these three goals. 
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WHAT IS THE PRIMPS FILE SYSTEM? 

The PRIMOS file system is Prime's implementation of a collection of 
objects and procedures that let you create, on a disk, a file storage 
structure as simple or as complex as you require to fulfill your data 
storage, access, and security needs. The structure is analogous to 
that of an inverted tree, consisting of a trunk (the disk), branches 
(the directories mentioned earlier), and leaves (your files — the 
ultimate target of most of your work with the file system). 

At its simplest, the tree consists of a trunk and one or more leaves, 
representing a storage volume containing one or more files. 
Optionally, you can interpose one or more branches (directories) 
between the trunk and the leaves, and include some other objects (whose 
functions will be described shortly) , to make your tree as complex as 
you wish. 

The objects that the PRIMOS file system is concerned with are 

• Disk Partition 

• Master File Directory (MFD) 

• Top-level Directory 

• Lower-level Directory 

• Segment Directory 

• Access Category 

• File 

There can be varying numbers of all of these objects on any given 
system. You can add a number of disk partitions to a system. Each 
partition contains one master file directory. Each master file 
directory can contain any number of the other file system objects. 

In order to get to any of these objects to operate on them, you must be 
able to identify each one uniquely. This means that each object must 
have a name. The person who creates an object assigns it a name. Disk 
partitions and top-level directories are usually assigned names by a 
System Administrator. You, the programmer, assign your own names to 
objects that belong to you: lower-level directories, segment 
directories, access categories, and files. 

Once you have created a tree structure suitable for- your purposes, you 
will want to store some data in it, and use the data that you have 
stored. The PRIMOS file system supports two access methods , or ways of 
reading and writing data: the Sequential Access Method (SAM), and the 
Direct Access Method (DAM). 

You will want to have some control not only over who has access to your 
files, but also over what kinds of things those who do have access can 
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do to your files. Other "users who share your system will want to 
exercise the same control over theirs. Typically, you might want all 
members of your department to be able to read your files, a select few 
to be able to change them or add to them, and you alone to be able to 
create and delete them. The PRIMOS file system gives you a variety of 
access control tools to establish whatever degree of control you wish 
over any^ some, or all of the objects that belong to you. These tools 
involve user identifications and a set of permissions , or access 
rights , which together make up Access Control Lists (AClis). An older 
form of access control, the directory password, is still supported, but 
its use is declining in favor of the access control list. 

In addition to allowing several disks to be connected to one computer 
system, PRIMOS permits you to connect two or more computer systems to 
each other in a network , and to operate on objects "belonging" to one 
system from one or more of the other systems. Objects that belong to a 
system different from the one you are working on are called remote 
objects , and access to them is known as Remote File Access (RFA). 
Access to remote objects is controllable, through ACLs, in the same way 
as is access to objects on your own system ( local objects ) . 



THE TREE STRUCTURE 

In the PRIMOS file system, data is stored in objects structured in the 
form of an inverted tree. Figure 1-1 shows a sample tree structure. 



FILE SYSTEM OBJECTS 

The tree structure is made up of file system objects . An object is a 
collection of data that has its own name, the name by which you can 
refer to the object when you want to do something with it. The 
paragraphs that follow describe each of these objects in detail. 



Disk Partition 

At the top of a tree structure is a disk partition , which may also be 
referred to as a logical disk or a volume, or even an MFD. 

Disk partitions are configured on physical disks. PRIMOS supports 
three kinds of physical disks: Cartridge Module Devices (CMDs), 
Fixed-media Disks (FMDs), and Storage Module Disks (SMDs). Each of 
these is available in several storage capacities; the total range of 
usable storage space provided by the three types is from approximately 
30 usable megabytes for the smallest CMD to approximately 620 usable 
megabytes for the largest FMD. Storage space is divided into surfaces , 
tracks (or cylinders ), and sectors , the numbers and capacities of which 
are physical properties of the devices, and vary from one type of 
device to another. All of the devices and their capacities and 
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Sample File System Tree 
Figure 1-1 
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physical characteristics are described in detail in the Operator ' s 
Guide to File System Maintenance . 

Each physical disk, when it is first introduced to the PRIMOS operating 
system, is initialized, or formatted , by a System Administrator or 
System Operator, using the MAKE command (described in the Operator ' s 
Guide to File System Maintenance ). One function of formatting is to 
create, on the physical disk, one or more logical disks, or partitions, 
by defining the starting surface number and the number of surfaces that 
make up the partition. (A partition may not be smaller than one 
surface.) Some physical disks can contain a single partition, while 
others either are required to be or operate more efficiently when 
configured into two or more partitions. The actual number of 
partitions that a physical disk ultimately contains depends both on its 
physical characteristics and on the uses to which it is put. The 
System Administrator's Guide , Vol. I, discusses the considerations 
involved in the planning and execution of disk partitioning. 

Another function of formatting is to create a file known as the Disk 
Record Availability Table (DSKRAT), which enables the file system to 
keep track of which physical records contain data and which physical 
records are available to have data stored in them. Each physical 
record on the disk is represented in this file by one bit, whose value 
is if the record is in use, and 1 if the record is available. The 
DSKRAT file typically occupies several contiguous physical records, 
starting at track 0, sector 2, on the first surface on the disk. The 
DSKRAT file has the same name as the disk partition. 



Note 

A physical record is not the same as the data or text records 
mentioned earlier. These might be called logical records , and, 
unless otherwise noted, will be what is meant whenever the term 
record is used. 



Another function of formatting is to provide the disk with a bootstrap 
file (named BOOT). This file contains machine-executable instructions 
that initiate the loading of the PRIMOS operating system, enabling 
PRIMOS to be loaded and started from any disk connected to the computer 
system. The bootstrap file consists of a single physical record, 
located at track 0, sector on the first surface of the disk. 

During formatting, the MAKE program may detect a "bad" sector, that is, 
a sector having a flaw that makes it impossible to record data into 
that sector reliably. When this happens, MAKE creates a file called 
the badspot file (named BADSPT) in which are recorded the locations of 
any such sectors that it encounters. The file system refers to this 
file in order to avoid attempts to write data to unreliable sectors. 
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The DSKRAT, BADSPT, and bootstrap files are largely invisible and of 
little direct interest to you as a programmer. The file system vises 
DSKRAT and BADSPT automatically , and the bootstrap record is normally 
invoked only by the system operator. 

The final object that formatting creates is the master file directory, 
beginning at track 0, sector 1, on the first surface of the partition. 



Master File Directory 

Every disk partition is organized in a hierarchy of directories, with 
one master file directory , called the MFD, at the top. Each directory 
contains a list of names and starting disk addresses of all of the 
objects that are immediately subordinate to it. The objects 
immediately subordinate to the MFD are top-level directories. The MFD 
can contain other information, such as who has access to these objects 
and how much disk space the objects are permitted to occupy (their 
quotas ) . The MFD is the starting point in any search for a file system 
object. To attach to the MFD, you issue the command: 



ATTACH <DISK_PARTITICN>MFD 



where <DISK_PARTITICN> is a name, but MFD is entered literally. 

Because "MFD" does not appear in a pathname displayed from anywhere 
other than itself, the term MFD is often used synonymously with disk 
partition to indicate the top of the file system tree structure. 



Top-level Directory 

A directory immediately subordinate to a master file directory is a 
top-level directory . System or Project Administrators often assign 
top-level directories to individual users as origin directories , 
although lower-level directories may be assigned just as well for this 
purpose. (An origin directory is the starting point for a user to 
access all of the file system objects belonging to him.) The objects 
that can be immediately subordinate to a top-level directory are 
lower-level directories, segment directories, access categories, or 
files. In addition to pointing to the objects it contains, a top-level 
directory also includes access control and quota information for them. 

Not all top-level directories are assigned as origin directories. On a 
disk partition containing the PRIMOS operating system, for example, a 
number of directories immediately under the MFD may contain objects 
such as command files, records of system usage, and other kinds of data 
that are related to system operation. 
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Lower-level Directory 

Any directory that is one or more levels below a top-level directory is 
a lower-level directory , or simply a directory. Lower-level 
directories can point to the same kinds of objects that top-level 
directories can point to, including more lower-level directories. 
Directories can be nested to many levels (99 is the default maximum 
number). While the nesting level limit depends on such factors as the 
physical capacity of the disk on which the directories reside and on 
quotas that may have been established on their superior directories, 
the real determining factor may be the length of the absolute pathname, 
which is limited to 128 characters. User access to and interaction 
with a lower-level directory whose pathname contains more than 128 
characters is uncertain, because the pathname is truncated. (Pathnames 
are explained in the section entitled OBJECT-NAMING CONVENTIONS later 
in this chapter . ) 



Segment Directory 

The directories described so far all fall into a class known as file 
directories . There is another class known as a segment directory , used 
primarily to contain program segments created by the PRIMOS SBG 
command, and multiple-index files such as those created by the 
MIDASPLUS subsystem. 

Segment directories can be contained in file directories just as any 
other file system object can. Bat they can point only to numbered data 
files and segment directories, and cannot contain the names of 
lower-level directories or other objects such as data files or access 
categories. Their main function is to increase the efficiency of 
certain utility and application programs through the use of numbered, 
rather than named, objects. Once the identifying number of an object 
is made known to PRIMOS, it is more efficient to locate and operate on 
than is an object identified by a pathname or a filename. 

A segment directory cannot be created explicitly by a command from a 
terminal. Rather, PRIMOS provides subroutines, expressly designed for 
this purpose, that can be included in any program that is intended to 
manipulate segmented files. You can see the evidence of a segment 
directory's creation by inspecting the contents of the file directory 
that contains it, but its actual creation is transparent to you as you 
sit at your terminal. 

Refer to Chapter 6, DATA STORAGE AND RETRIEVAL, for further information 
on segment directories and to the Subroutines Reference Guide , Vol. II, 
and the SEG and LOAD Reference Guide for information on segmented 
programs. 
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Access Category 

An access category is a directory entry that contains an access control 
listT When you specify that a certain set of users have specific 
rights to operate on one of your file system objects, that list of 
users and rights (the ACL) takes up space in the directory that 
contains the object. If a number of objects require the same list, 
creating that list for each individual object becomes wasteful, and it 
is useful to be able to specify this common list by defining it once 
and having it reside in only one place. The function of the access 
category is to contain the list; the access to each object can then be 
set by referring to the name of the access category. 

The subject of access control and ACLs is explained in more detail in 
the section entitled ACCESS CONTROL later in this chapter. 



File 

A file is an object that contains a collection of user data. In this 
broad sense, any file system object can be thought of as a file, since 
all objects presumably contain information useful to their users. A 
top-level directory, for instance, has information that its user, the 
file system, „, uses in its search for file system objects. But a file, 
from the point of view of the human user, contains no pointers to 
further subordinate objects; it is a leaf at the end of a branch in 
the tree structure. 

There are system files and user files. System files are created by 
PRIMOS or its administrators and operators for use by the operating 
system. Some of them can be read by users for purposes such as listing 
users on the system and getting status information of various k i n ds. 
But because of the access controls usually applied to them and their 
directories, few system files, if any, can be changed or deleted by the 
ordinary user. 

User files, on the other hand, are created by you and other users to 
fulfill the needs of your application programs. You normally create 
structured data files by running your application programs, or text 
files by using a text editor or word processing application. You can 
control access to your files as tightly or as loosely as you wish to 
satisfy your security needs and those of any group(s) you may belong 
to. 



OBJECT-NAMING CONVENTIONS 

Every directory, access category, and file must have an identification 
that is unique within the entire collection of objects known to the 
file system. This requirement appears, at first glance, to place a 
heavy burden on you — that of knowing about the name of every existing 
object any time you want to assign a name to a new object. But PRIMOS 
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eases this burden in much the same way as a mailing address enables the 
Postal Service to locate a particular John Smith: by using a 
hierarchical access path to John Smith through a state, city, street 
name, and house number. It is this access path that is unique, even 
though some of the individual components may not be. 

It is only a small step from the Postal Service's access path to the 
file system's access path — the state is the top-level directory; the 
city and street name are lower-level directories, the house number is a 
file, and the individual Smiths living in the house are records. (At 
the uppermost level, the United States is the disk partition; other 
countries are different partitions.) 

The mailing address is interpreted by reading geographical elements in 
a specific order, from the most inclusive to the least inclusive. The 
file system's access path is formed and interpreted in precisely the 
same way, by combining the names of file system objects in order, from 
the most to the least inclusive. The resulting string of names (plus 
some separators to show where one name ends and another begins) is 
called a pathname , and, for the file system, it is only this pathname 
that must be unique. 

Thus, the only uniqueness requirement you must satisfy is that, within 
a given directory, each object must have a unique name. This is the 
same as saying that in a given city there can be only one Washington 
Street (but there could be a Washington Street in every city in the 
country) . 



Object Names 

An object's name is a string of up to 32 characters selected from the 
following set: 



letters (A through Z) 

digits (0 through 9) 

special characters _ # $ - . * & / 



An object name cannot begin with a digit or contain any spaces. Also, 
you should avoid names beginning with _, -, &, and $, because they can 
cause confusion in certain commands and syntaxes. You can use the 
underscore (_) to represent a space if you want your object name to 
consist of two or more words. Use the period (.) for separating 
object name components. 

An object name can consist of one or more components . When there are 
two or more components in an object name, each is separated from the 
next by a period. Components can be used for whatever purpose you 
wish, such as to identify several objects as being related to each 
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other in some way. As a programmer, you will use components as 
suffixes to source-text filenames to identify the language used in 
writing your programs (for example, .FTN for FORTRAN programs, or .CBL 
for COBOL programs) . PRIMOS provides subroutines whose functions are 
to manipulate suffixes. Refer to the Prime User's Guide for an 
explanation of components and for a list of suffixes that Prime 
software recognizes. 

Although the file system allows up to 16 components in an object name, 
two or three are usually sufficient for most practical applications. 
In any case, remember that an object name, including all components and 
their periods, cannot be more than 32 characters long. 



Pathnames 

A pathname is a string of object names representing the access path 
that the file system follows to get to a specific object. There are 
several kinds of pathnames, detailed in the following paragraphs. 

Absolute Pathname : From the file system's point of view, an object's 
pathname contains the name of each directory level that must be crossed 
to get to the desired object. Such a pathname is called an absolute 
pathname . It begins with the name of the disk partition, and continues 
with the names of progressively less inclusive directories until the 
one containing the desired object is reached. It ends with the name of 
the object. A pathname cannot be more than 128 characters long. 

The name of the disk partition is enclosed in <> symbols, and each 
subsequent directory name is separated from the next by a > symbol: 

<disk_paitition>top-level_dir>lower-leveljiir> . . . >objectname 

Relative Pathname : As a terminal operator or a programmer, you will 
often need to supply only part of an absolute pathname: the part that 
follows the name of the directory you are currently working in. This 
kind of pathname is called a relative pathname ; it is relative to the 
directory you are in. It can be used because the file system 
"remembers" the elements of the absolute pathname that precede and 
include the name of this directory. Most commands that you will invoke 
from your terminal, as well as many of the file system subroutines you 
will write into your programs, allow you to use relative pathnames. 

You use a relative pathname whenever you want to work on an object that 
is subordinate to the directory you are currently in, but not 
immediately subordinate to it; that is, when one or more directory 
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levels exist between the one you axe in and the object you want to 
address. The form of a relative pathname is: 



*>lower-level_dir> . . . >objectname 



Here the asterisk (*) represents the part of the pathname that the file 
system "remembers, " and when it is combined with the elements that you 
supply explicitly, the result is an absolute pathname that leads from 
the disk partition to the object. The part of the pathname represented 
by the asterisk is called the home , or working , directory pathname; 
the directory itself is the home, or working, directory. In Figure 
1-1, if your home directory is BRANCH1,. the home directory pathname 
represented by the asterisk is <PQREST>BEECH>BRANCH1 . The part of the 
pathname that you would supply after the asterisk to get to the file 
LEAF6 in lower-level directory BRANCH8 would be >BRANGHB>LEAF6, giving 
the following relative pathname: 



! >HRANCH8>LEAF6 



This, in turn, is interpreted by the file system as the absolute 
pathname: 



<FCREST>BEECH>BRANCH1 >BRANCH8 >LEAF6 



Simple Pathname : When the object you want to address is immediately 
contained in your home directory, you can use an even simpler form of 
pathname, known as a simple pathname. A simple pathname consists of 
only the name of the object you want to work with; it does not contain 
any > symbols. Cbjectname, entryname, and simple filename are terms 
used synonymously with simple pathname. If , as in the last example, 
your home directory is BRANCH1, and you want to do some operation on 
the directory BRANCH8, you can use the simple pathname BRANCH8. 



Note 

There is an exception to the interpretation of a simple name 
when you use the ATTACH command. If, using the example above, 
you attempt to attach to BRANCH8 by issuing the command 



ATTACH ERANCH8 



the ATTACH command interprets BRANCH8 as a full pathname 
(described below) rather than the simple pathname of the 
subordinate directory ERANCH8. The result is that PRIMOS 
searches for a top-level directory of that name, and in all 
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likelihood, will fail to find it. To attach to the lower-level 
directory BRANCHB, you would use a relative pathname: 



ATTACH *>BRANCH8 



Full Pathname : A full pathname is one in which you explicitly call out 
all of the pathname elements except the first (the disk partition) . 
The file system assumes that the first element that you specify in a 
full pathname is the name of a top-level directory. In Figure 1-1, a 
full pathname might be: 



BEECH>BRANCH1 >TWIG4 



When you specify a full pathname, you are asking the file system to 
search all of the active disk partitions that are visible to your 
system to find the first occurrence of that top-level directory. If 
your system is part of a network, all visible disk partitions on all of 
the active systems on the network are searched. Local disks are 
searched first, in order of logical disk number, and then remote disks 
are searched in the same manner. This can take some time. (You can 
limit the scope of such a search, or change the order in which disk 
partitions are searched by modifying the ATTACH$ search list. Search 
lists are described in Chapter 3, SEARCH RULES.) The search ends when 
the first (or only) top-level directory with the specified name is 
found. That top-level directory, and any intervening lower-level 
directories specified in the pathname, are then followed to the desired 
object. 

There are three points you must understand about a file system search 
by full pathname: 

• Once a top-level directory with the specified name is found on 
any disk, the search terminates. 

• If the desired object and all intervening lower-level 
directories specified in the pathname exist under that 
directory, PRIMOS performs whatever operation you requested on 
the object. 

• If the desired object or one of the lower-level directories 
specified in the pathname does not exist under that top-level 
directory on that disk partition, the file system returns an 
error message and aborts the search, even though the required 
full pathname may exist on another partition (either on the same 
system or on another system in the network). 

The implication of this file system search method is that, if you want 
to use a full pathname and be sure of finding the object you want to 
operate on, all of the objects named in the pathname must exist within 
the directory that begins the pathname, and the directory that begins 
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the pathname must he unique on your system (and on any other systems 
that may share a network with your system). Your System Administrator 
may take the responsibility for uniqueness of top-level directories, 
but if there is no guarantee of uniqueness, it is always safer to use 
an absolute pathname. 



How and When Objects Are Named 

You assign a name to a file system object when you create it; how you 
create it depends on the kind of object you are creating. 

A text file such as a memo or a source program is normally created by 
using an editor program, and is named by specifying a filename the 
first time you ask the editor to store it. Different editors have 
different ways of doing this, documented in their respective manuals 
and user's guides; storage commands usually take the form of a FILE, 
STORE, SAVE, or WRITE. 

Application-related data files are usually created by a user program 
that executes an open file subroutine. If it does not find the name of 
the file it is asked to open, the subroutine creates the file and 
assigns the given name to it. The subroutine call also cont ains 
information as to the type of file to be created, and whether it is to 
be opened for input, output, or both. 

File directories, lower-level directories, and access categories can be 
created either by executing a subroutine in a user program or by using 
a PRIMOS command at a terminal. 

Segment directories are created by various application programs that 
manipulate segmented files. User programs can call subroutines to 
create segment directories. 



ACCESS METHODS 

PRIMOS provides two means of file access: the Sequential Access Method 
(SAM) and the Direct Access Method (DAM). In both access methods, the 
file appears as a linear array of words indexed by a current position 
pointer. 

Using a SAM file, your program can read or write a number of halfwords 
beginning at the pointer, which is advanced as the halfwords are read 
or written. File system subroutines enable you to position the pointer 
anywhere within an open file, and to read and write data sequentially 
from that point. File data can be transferred anywhere in the 
addressing range. When a file is closed and reopened, the pointer is 
automatically returned to the beginning of the file. 

With the direct access method, the file also appears to be a linear 
array of halfwords. This method, however, has faster access times in 
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positioning operations, since ERIMOS keeps an index to allow fast 
random positioning. Subroutine oalls to manipulate SAM and DAM files 
are identical. 



ACCESS OONTROL 

Two requirements must be met before your program can operate on a file 
system object: 

• Your program must be attached to the file directory that 
contains the desired object, and, so that this can happen, 

• Your program's user must have at least Use access to that 
directory 



Attaching to a File Directory 

You can attach your program to the directory containing the desired 
object in one of two ways: 

• Explicitly, if you invoke the ATTACH command specifying the 
pathname of the file directory before you invoke your program 

• Implicitly, if you do not explicitly attach to the file 
directory, but supply any form of pathname other than a simple 
object name when you invoke your program 

When you explicitly attach to a file directory by using the ATTACH 
command, that directory becomes your home directory. You can then 
invoke your programs using simple object names as arguments; your 
programs will locate their target objects provided they are immediately 
contained in that directory. 

For example, if you write a program called COUNT to count the number of 
lines in a text file, and install it in the directory MYDIR. MEMOS, one 
way you can invoke it is: 



ATTACH MYDIR. MEMOS 
RESUME COUNT CHARITY 



Since the COUNT program was invoked with the simple object name CHARITY 
as its argument, COUNT looks in the home directory MYDIR. MEMOS, 
established by the ATTACH command, for the file CHARITY. 

You do not always need to attach explicitly to a file directory before 
invoking your programs; they can still operate on objects outside the 
home directory if you supply the object's relative, full, or absolute 
pathname rather than its simple name. Taking the COUNT program again 
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as an example, and still assuming the same home directory, you could 
invoke it in the following way: 



RESUME COUNT INIT_DIR>IjCX;IN.CPL 

For this invocation, COUNT has to go to a directory INITJDIR, outside 
the home directory, to locate the file IOGIN.CPL. To do this, it 
attaches temporarily to the outside directory by means of a current 
attach point ; the target directory is called the current directory . 

If you want to enable your programs to operate in both of the ways 
shown in these examples, you must use the SRSFX$ subroutine, which is 
capable of searching for objects outside as well as within the home 
directory. The SRCH$$ subroutine can search only in the home 
directory; if you use it in a program, and the target object is 
outside your home directory, you will have to attach to the directory 
containing the object before invoking the program, as in the first 
example. 



Note 

The TSRC$$ subroutine, which is capable of searching for an 
object outside the home directory, is considered obsolete at 
PRIMOS Rev. 20.2. Although TSRC$$ is still supported, programs 
should use SRSFX$ beginning with Rev. 20.2. At Rev. 21.0, 
OPSR$ and OPSRS$ are supported for use with Search Rules. 
These two subroutines are described in Volume II of the 
Subroutines Reference Guide . Refer to Chapter 3, SEARCH RULES, 
for a description of the search rules facility. 

The intent of the current attach point is that the attachment is in 
effect only for the duration of the program's execution. When the 
program terminates, the attach point should revert to the home 
directory. This is especially important if the program does not 
terminate normally; in order to provide a consistent result in cases 
of abnormal termination, most Prime software resets the current attach 
point to the home directory whether it terminates normally or 
abnormally. 

Attach points and the subroutines that manipulate them are described in 
more detail in Chapter 4, ATTACH POINTS. 



Access Control Lists 

As stated earlier, users must have access to all directory levels 
leading to the objects they are working on, as well as to the objects 
•themselves. The means by which you as a programmer are given access, 
and by which you can control access, to the various directories and 
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files involved in your daily work are clearly explained in the Prime 
User's Guide . As a programmer of utilities and applications for other 
users, however, you need to he aware of the kinds of things your 
programs can and should do to enable those users to control access to 
the objects these programs create and use. 

PRIMOS provides a set of subroutines that you can write into your 
programs to enable them to manipulate access control lists (ACLs) in 
precisely the same way as you can by issuing ACL-related commands at 
your terminal. For example, if you write a program that constructs a 
data base for a group of users, it is particularly useful for that 
program to be able to establish a data base ACL for that group of users 
at the time the data base is created. Or, consider a utility program 
that creates new files at various times, all of which should be 
identically protected. Using subroutine calls, this program can create 
an access category to which each new file is linked when it is created. 

An access category, while it takes more disk space than a single access 
control list (about as much as two average ACLs) , saves disk space when 
the same ACL is to protect more than two objects; this is because any 
number of objects can be linked to the access category once it is 
created. Your program can make these links when it creates its files, 
after it checks to see whether the access category already exists. 

You can use an access category to synchronize the access to multiple 
objects when rights are added or removed from the access category's 
ACL: whenever a new right is added or an old right is removed, the 
change applies to all objects protected by the access category, 
removing the need to update each object's ACL individually. 

The access rights that you can assign to your own file system objects 
(using PRIMOS commands) and that your programs can assign to their 
objects (using access control subroutines) are all fully described in 
the Prime User's Guide . In the Rev. 21.0 release of PRIMOS, you can 
specify ALL to include 0PDALUR\?X, all of the rights supported at this 
rev. (If some future rev. of PRIMOS supports new access rights, you 
will not get them automatically when you read in your Rev. 21.0 file 
that has been assigned ALL. You will have to reassign ALL or add the 
new rights individually.) 

Access control subroutines can deal with both individual users and 
groups of users. Your System or Project Administrator can define a 
user group (whose group name begins with a period, such as .DBUSER) 
consisting of the user identifications of all of the users of a 
particular utility or application program. Your programs can use the 
access control subroutines to grant or deny access to these groups as 
well as to individuals. 



Password Directory 

In an older form of file access control, PRIMOS allows a limited set of 
access rights to be specified on a per-file basis. A file directory 
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can be given an owner password and a non-owner password and a set of 
rights for each: R (read), W (write), and D (delete) . This form of 
protection is giving way to the more comprehensive ACL mechanism, and 
will not be further described in this book. Details can be found in 
the Prims User's Guide , as can procedures by which you can convert the 
older form to the ACL form. 



HOW AND WHEN ACCESS IS CALCULATED 

In most situations, users need not be concerned about when access is 
actually calculated by PRIMOS. However, there are some subtleties of 
the ACL mechanism that the advanced user should be aware of. This 
section discusses: 

• Access calculation concepts 

• Access calculation when opening files 

• Access calculation when attaching to directories 

• Access calculation for other operations 



Access Calculation Concepts 

For a given file system operation, there are two times that relate 
directly to the ACL mechanism: 

• When access is read 

• When access is used 

For the most part, reading and using occur at the same time. A sample 
case is the deletion of a file. When you delete a file, PRIMOS first 
reads the access for that file, and then it uses that access to 
determine whether or not you may delete the file. 

When you attach to a directory, however, the access is read once. It 
is then used immediately to determine whether or not you may attach to 
the directory. If you are allowed to attach, PRIMOS remembers the 
access it read for the directory. Subsequent operations within and 
upon that directory may reuse the access that PRIMOS read when you 
first attached. Therefore, if you attach to a directory, and then 
change the access for that directory, you will find that for certain 
operations the access change has not taken effect. The access 
information read for a home or current directory is not discarded until 
you attach away from the directory. 
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The following example illustrates an effect of this behavior. 



CK, ATTACH COGENT 

OK, CREATE SENORA 

CK, ATTACH O0GENT>SENORA 

CK, LIST_ACCESS 

"<Current direetory>" protected by default ACL (from "<Xl>COGENT"): 

COGENT: ALL 

$REST: LUR 
CK, LIST-ACCESS OCGENT>SEN0RA 
"CCGENT>SENORA" protected by default ACL (from "<X1>CCGENT"): 

COGENT: ALL 

$REST: LUR 
CK, LD 

<XL>CDGENT>SENCRA (ALL access) 

1 record in this directory, 1 total record out of quota of 0. 

No entries selected. 

CK, SET_ACCESS COGENT >SENORA COGENT :U -NOjQUERY 
CK, LIST_AOCESS 

ACL protecting "<Current directory>": 

COGENT: ALL 

$REST: LUR 
CK, LIST_ACCESS CCGENT>SENaRA 

ACL protecting " COGENT >SENCRA" : 

COGENT: U 

$REST: NONE 
CK, LD 

<Xl>O0GENT>SENCRA (ALL access) 

1 record In this directory, 1 total record out of quota of 0. 

No entries selected. 

CK, ATTACH 00GENT>SENCRA 

CK, LD 

Insufficient access rights. (current_directory) (Id) 

ER! 



In this example, LIST_AOCESS commands are invoked at different times to 
illustrate the difference between the home directory and the same 
directory when referenced explicitly by pathname. In the first two 
invocations, LIST_ACCESS reports the same access when the directory is 
referenced as the home directory and when it is referenced by pathname. 
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Then, without changing the home attach point, you set the access to the 
home directory so that you have only Use access. Among other things, 
this removes List access from the ACL on the SENORA directory. 

At this point, the third LIST-ACCESS command on the home directory 
shows that you still have ALL access to SENORA. A fourth LIST_ACCESS 
command on the same directory (using the pathname) reports that you 
have only Use access. This discrepancy is illustrated further by the 
fact that you can still type LD and see the directory contents (or lack 
thereof) . 

However, when you reestablish SENORA as the home attach point, PRIMOS 
reads the new ACL for this directory. This results in your having only 
Use access to the home directory, which prevents you from examining the 
directory contents using LD. It is when you attach again to the 
lower-level directory that the new ACL takes effect. 

Similarly, the new ACL will take effect for any other users that attach 
to the directory, but not for users who were already attached to the 
directory when the ACL on it was reset. 



Access Calculation When Opening Files 

When opening a file or segment directory, the access is read and used 
when the open operation first takes place. The access is not used 
again during read or write operations. The access will be used if a 
change-access operation is performed (by using the SRCH$$ subroutine 
with the K$CACC key). However, the access is not read again in this 
case. Therefore, once a file is open on a file unit, changing the 
access of the file does not affect any operations performed on that 
file unit up until the time that file unit is closed. (See the FILE 
UNITS section, following, for an explanation of file units.) 



Access Calculation When Attaching to Directories 

When you attach to a directory, as either a home or a current 
directory, PRIMOS reads and uses the access on the directory during the 
attach operation. Subsequent operations on the home or current 
directory use the access without reading it again, as illustrated 
earlier. However, subsequent operations on the same directory when the 
name of the directory is specified will cause PRIMOS to read the access 
for the directory to check the access rights for those operations. 
Once PRIMOS has read the access for the directory, it does not update 
any access it has already read for the origin, home, or current 
directories . 
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The following example illustrates these points. 



CK, ATTACH COGENT 

OK, CREATE SENCRA 

OK, ATTACH OCGENT>SENORA 

OK, ED 

INPUT 

A TEST FILE. 

EDIT 

FILE TESTJFILE 

CK, LIST_ACCESS TEST_FILE 

"TEST_FILE" protected by default ACL (from "<X1>CCGENT"): 

COGENT: ALL 

$REST: LUR 
CK, SET_ACCESS COGENT >SENORA COGENT :ALURW 
OK, LIST_ACCESS TEST_FILE 

"TEST_FILE" protected by default ACL (from "<X1>CCGENT"): 

COGENT: ALL 

$REST: LUR 
CK, LIST_ACCESS OCGENT>SENORA>TEST_FILE 

"CCGENT>SENCRA>TEST_FILE" protected by default ACL 
(from "<Xl>COGENT>SENORA"): 

COGENT: ALURW 

$REST: NONE 
CK, DELETE COGENT >SENORA>TEST_FILE 

Insufficient access rights. Unable to delete "CCGENT>SENORA>TEST_F 
ILE" (delete) 
CK, DELETE TESTJFILE 
CK, 

Here, an attempt to delete a file by pathname fails because the access 
on its parent directory denies Delete access to the user. However, 
because the user was attached to the parent directory before the access 
was changed to deny Delete access, deleting the file as a member of the 
home directory succeeds. 



Access Calculation for Other Operations 

Aside from opening files and attaching to directories, most file system 
operations cause PRIMOS either to use the access for the current 
directory or to read and use the access for the appropriate file system 
object just once. For example, renaming a file causes PRIMOS to use 
the access for the current directory and make certain that both Delete 
and Add rights are granted. 
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FILE UNITS 

A file vpit is an open channel to a file, a segment directory, or a 
file directory. Through this channel, your programs read data from and 
write data to a file system object. Associated with a file unit is a 
file unit number , that is, a numeric pseudonym for the object's name. 
This number is assigned either by the program (static allocation) or by 
PRIMOS (dynamic allocation) when the program opens the file (see File 
Unit Number Allocation , later in this section). It uniquely identifies 
the file unit for a particular process (user). 

Generally speaking, your program performs the following operations to 
operate on a file system object: 

1. Opens the file: establishes ah open file unit and assigns a 
file unit number. 

2. Accesses the file: the open file unit enables operations on 
the file. 

3. Closes the file unit: revokes access to the file. 



Information Associated With a File Unit 

As described previously, a file unit identifies an open file system 
object. Internally, PRIMOS maintains information on each open file 
unit. 



Current Object Position : The current object position points to the 
location in the file system object at which the next data read or write 
begins. For files, the position points to a particular halfword in the 
file. For segment and file directories, the position points to a 
particular entry in the directory. 

The current object position is adjusted automatically by PRIMOS as data 
is read from or written to an object. In addition, your program may 
change the current object position without reading or writing data by 
using the PR¥F$$ subroutine, described in Chapter 5, TEXT STORAGE AND 
RETRIEVAL. 

For files, the current object position is always between and the 
end-location of the file, or end of file, inclusive. The end-of-file 
location is the same value as the number of halfwords in the file; 
when a file is first created, the end-of-file location is 0. 

To append new data to the end of an existing file, first position the 
file unit to the end-of-file location, which represents the position of 
the next halfword to be appended to the file. (If you do not know the 
end-of-file location, simply position to the largest possible halfword 
number, 2147483647. Although PRIMOS returns an error code of e$eof to 
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indicate that the end of file has been reached, FRIMOS sets the current 
abject position to the end-of-file location.) 

At the end-of-file position, writing data to the file automatically 
extends the file as the data is written; an attempt to read data at 
this point returns the error code e$eof (end of file). 

Open Mode : The open mode determines what operations are valid for an 
open file unit. A read operation requires the file unit to be open for 
reading; a write operation requires the file unit to be open for 
writing; both operations are valid if the file unit is open for both 
reading and writing. 

Your program sets the open mode when it first opens a file. Your 
program can open a file for reading, for writing, or for both reading 
and writing. To do this, the user running your program must have the 
corresponding access to the target object. For files and segment 
directories, the required access is Read, Write, or both Read and 
Write, to match the actions for which they axe opened; for file 
directories, which axe open only for reading, List access is required. 

A special open mode, known as virtual memory file access read 
(VMFA-read), also exists. The FRIMOS executable program format (EPF) 
mechanism uses VMFA-read to map an EFF into virtual memory from the 
disk. A file unit open for VMFA-read cannot be read or written by a 
program. 

When your program tries to open a file unit to an object for a specific 
action such as writing, another file unit may already be open to that 
object for the same purpose. In such cases, FRIMOS checks the open 
mode requested by your program against the read/write lock then in 
effect for the object. Your program's open request is rejected if the 
lock specifies that only one user at a time can do what the open 
request intends to do, and 

• Another user is already using the object for that purpose, or 

• Your program has already opened the object on another file unit 
for the same purpose. 

See the section entitled The Read/Write Lock Attribute , later in this 
chapter for the meanings of the possible values for the lock. 

Your program can change the open mode of a file if the new open mode 
does not conflict with the access or read/write lock controls described 
above. The CH$MOD subroutine, described in the Subroutines Reference 
Guide , Vol. II, performs this function. 
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Ctojeot Type : The type of the object open on a file unit determines 
what kinds of operations are valid on that file unit. Ctojeot types 
include: 

• SAM and DAM files, for which most operations (except directory 
operations) are valid, such as data read and data write 

• SAM and DAM segment directories, for which only segment 
directory operations are valid, such as position to segment 
directory member and delete segment directory member 

• File directories, for which only file directory operations are 
valid, such as read next directory entry and read named 
directory entry 

Access categories cannot be opened on a file unit; they are restricted 
in size, so they are read and written in single operations and do not 
require an associated file unit. 

If your program attempts an operation that conflicts with the object 
type, PRIMOS returns one of several error codes: 

• e$dire (Operation illegal on directory), indicating an attempt 
to perform an operation valid only for SAM or DAM files on a 
segment or file directory 

• e$ntsd (Not a segment directory), indicating an attempt to 
perform an operation valid only for segment directories on a 
file or file directory 

• e$ntud (Not a top-level directory), indicating an attempt to 
perform an operation valid only for file directories on a file 
or on a segment directory 

Because these object types are all opened in the same way, these errors 
are returned only when your program attempts to perform the invalid 
operation, typically after opening the object. To enable your program 
to detect an inappropriate object type earlier, have it check the type 
value returned by the subroutine it calls to open the object. If the 
type value is not appropriate to the intended operations, your program 
should close the file unit and report an error. 



Object Modified : An object-modified flag is initially reset when a 
file unit is first opened (before the object is modified). When the 
first data write is performed on the object, this flag is set (after 
the object has been modified). 

When the file unit is later closed, PRIMOS uses the object-modified 
flag to determine whether the date and time last modified (dtm) field 
for the object should be updated. If the flag is not set, PRIMOS does 
not update the dtm field. Therefore, simply opening a file for writing 
and then closing the file does not cause the dtm field to be updated. 
(The date and time last accessed field is set under this and other 
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circumstances described later in this chapter.) A program must 
actually write data to the file and then close the file to update the 
dtm field. 



Disk Shut Down : A disk-shut-down flag is Initially reset (meaning the 
disk is not shut down) when a file unit is first opened. If a disk 
partition is shut down by the System Administrator or System Operator 
(by using the SHUTDN command) , the disk-shut-down flags for all file 
units open to objects on that disk are set (meaning the disk is shut 
down). After that, any attempt by a program or user to continue 
performing operations on an affected file unit is rejected with the 
error code e$shdn (Disk has been shut down). 



Calculated Access to Object : When your program opens an object, PRIMOS 
calculates the user's access to the file to make sure that the user can 
operate on the file. PRIMOS records the resulting summary of the 
user's access to the file in the information for the corresponding file 
unit. A later attempt by your program to change the open mode of the 
file is checked against this copy of the user's access, not against the 
current access on the object itself (which may have changed since the 
file unit was opened). 

Read/Write Lock : PRIMOS records the read/write lock of an open file 
unit in the information for that file unit so that it can quickly 
determine whether record-level locking for writes is necessary. If at 
least two file units are open to the same object for writing, or one is 
open for reading and another is open for writing, PRIMOS must ensure 
that simultaneous operations on those file units result in predictable 
behavior. Because such a situation is permissible only when the 
read/write lock is set to an appropriate value, PRIMOS checks the 
read/write lock for the file unit to determine how careful it must be 
in guarding against simultaneous access during a read or write. The 
more permissive the read/write lock setting, the more care PRIMOS has 
to take, and the lower the performance of each read or write operation 
will be. 



OPENING A FILE 

Your program may open a file for reading only, for writing only, for 
both reading and writing, or for VMFA-read (EPFs only). If your 
program opens a file for reading only, your program can read the file, 
but cannot change the file. If your program opens a file for writing 
only, your program can write the file, but cannot read the file. 

To open a file, your program calls one of many system subroutines, 
described in Chapters 5, TEXT STORAGE AND RETRIEVAL and 6, DATA STORAGE 
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AND RETRIEVAL. Each subroutine provides different functionality for 
opening a file, but they all provide the following services. 

• Search the specified file directory (if a pathname is specified) 
or the current directory (if a simple object name is specified) 
to see whether the requested filename is there. 

• Create the file if the filename is not present and your program 
is opening the file for writing or for both reading and writing. 
If the filename is not present, and your program is opening the 
file for reading only, these subroutines return a "not found" 
indicator. 

• Determine a file unit number. The file unit number is the only 
identifier PRIMOS uses for transferring data to and from the 
file. 

• Set up tables and initialize buffers in the operating system. 

If your program opens a file for writing only, or for reading and 
writing, your program may change that file. If the system subroutine 
creates a new file at the time of opening, no information is contained 
in the file. 

Because open-for-write files are subject to alteration (deliberate or 
accidental), your program should keep files closed except when they are 
being used. Open files absorb system resources; they may also be 
unavailable to other users. However, frequent open and close 
operations also absorb system resources; therefore, try to balance 
your program's use of files so that open and close operations are 
infrequent without resulting in file units being open but inactive for 
long periods of time. 

When the user is communicating with the file structure through one of 
the standard Prime translator or utility programs, files are referred 
to by name only. PRIMDS, or your program, handles the details of 
opening or closing files and assigning file units. For example, the 
user can enter an external command such as ED FILE1, which loads and 
starts the text editor and takes care of the details of assigning the 
file FILE1 to an available unit for reading or writing. 



File Unit Number Allocation 

PRIMOS allows two ways of allocating file unit numbers: 

• Dynamic allocation 

• Static allocation 

Dynamic allocation allows a program to leave to PRIMOS the task of 
selecting an available file unit number. When opening a file, a 
program specifies dynamic file unit allocation, and PRIMOS returns to 
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the program the file unit number it has assigned to the open file. The 
program then uses this file unit number when reading or writing the 
file. 

Static allocation is performed by a program. When opening a file, a 
program passes the file unit number to PRIMOS. If the specified file 
unit is already in use, PRIMOS rejects the attempt to reuse the file 
unit; otherwise, PRIMOS uses the program-defined file unit number to 
read or write the file. 

Dynamic allocation is the recommended method for most programs. Its 
advantages are as follows: 

• You do not have to worry about different parts of your program 
having conflicting file unit number requirements. 

• Your program can call another program that also uses dynamic 
unit allocation without causing file unit number conflicts. 

• A very large number of file units (32761) are available when 
using dynamic allocation, whereas static allocation allows a 
maximum of 126 file units open simultaneously for a given user. 

• Your program is guaranteed exclusive use of file units. 

Static allocation offers very few advantages; these rarely outweigh 
any of the advantages of dynamic allocation: 

• You can design several programs that are to run together as a 
package so that they use agreed-upon statically allocated file 
unit numbers; thus, these programs do not have to pass 
dynamically allocated file unit numbers back and forth to each 
other. 

• Your program can use a numerical constant as the file unit 
number, rather than requiring the use of a variable. 

• Prime translators do treat certain file unit numbers specially 
(when enabled using the -ATiTOy_PPJX33NNECTION option), so your 
program may use these file unit numbers if it invokes Prime 

translators . 



File Unit Numbers 

File unit numbers 1 through 127 (1 through 15 under PRIMOS II) may be 
specified for static allocation by your program. File units 127 
through 32761 are returned by PRIMOS only when your program requests 
dynamic unit allocation. Your program cannot specify a file unit 
number between 128 and 32761 (inclusive) when opening a file system 
object. 
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Unit 16 is reserved for system vise under PRBDS II; however, this fact 
is rarely important to consider, as any program linked by BIND or SBG 
cannot run under PRIMOS II. 

Unit -4 is the command output file unit. Your program should not read 
data from or write data to this file unit. Your program may read the 
current object position of this file unit, or use GPATH$ to obtain the 
full pathname of the command output file. 

Unit -1 is the current directory; unit -2 is the home directory; unit 
-3 is the origin directory. These three units are usually open to the 
corresponding directories. You may use this knowledge to perform 
certain operations efficiently. For example, to read the directory 
entries in the user's origin directory, your program can simply call 
DIR$RD using the k$init key the first time for file unit -3. It does 
not have to attach to the origin directory (thus preserving the current 
attach point) or to open the origin directory for reading (thus saving 
time and a file unit). 



File Pointer 

Once your program has opened a file, a file pointer is associated with 
the file unit. To understand how the file pointer works, imagine that 
the halfwords in a file are serially numbered beginning at halfword 
number 0. The file pointer is the number of the next halfword to be 
processed in a file. It identifies the point at which data are read 
from and written to the file. As your program reads and writes 
halfwords, the associated file pointer is incremented once for each 
halfword read or written. If your program reads a line of text, for 
example, the file pointer is positioned, after the read, to the 
beginning of the next line of text in the file. 



Positioning a File 

Your program can move the file pointer backward and forward within a 
file without moving any data. This is called positioning a file , and 
is described in more detail in Chapter 5, TEXT STORAGE AND RETRIEVAL. 
The value of a file pointer is called the position of the file . 
Positioning a file to its beginning is often called re w i nding a file . 



Truncating a File 

Your program can shorten a file by truncating it. When your program 
truncates a file, the part of the file that is located at or beyond the 
file pointer is eliminated from the file, and an end-of-file mark is 
placed at the pointer position. If the file pointer is positioned at 
the beginning of the file, all of the information in the file is 
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removed, but the filename remains In the file directory. If the file 
pointer is positioned at the end of the file, the truncation has no 
effect . 

PRIMOS handles the returning of disk space occupied by truncated 
records to the free record pool on the disk. 

Many programs truncate a text file just before closing it if they have 
written new information to the file. Because text files are typically 
variable-length record files, as described in Chapter 5, TEXT STORAGE 
AND RETRIEVAL, they are usually written from beginning to end; even if 
only one line in a file is changed, the entire file is rewritten in 
case the new line is longer or shorter than the line it replaces. In 
the process of rewriting an entire file, a program may write a new 
version that is shorter than the old version. Truncating the file 
ensures that old data is not left at the end of the new file. 



CLOSING A FILE 

Your program should always close a file before terminating execution, 
whether termination is normal or abnormal. Closing files is described 
in more detail in Chapters 5, TEXT STORAGE AND RETRIEVAL and 6, DATA 
STORAGE AND RETRIEVAL. 



Closing on Normal Program Termination 

Your program may close a file unit, also referred to as closing a file, 
when it finishes its processing of the file. When your program does 
this, the file unit number and the corresponding table areas in the 
operating system are "cleaned up" and released for reuse by another 
program or user. 



Closing on Abnormal Program Termination 

When control returns to PRIMOS by way of an error condition, files are 
not normally closed. To provide this functionality in your program, 
have your program close any file units it opened when it detects a 
fatal error. (Of course, your program should still report the original 
error; be careful to separate error code variables used to clean up 
after an error from error code variables used to detect original 
errors.) 

You may also choose to have your program make an on-unit for many 
system error conditions, as described in the Subroutines Reference 
Guide , Vol. III. If one of these conditions occurs while your program 
is running, your program can close any file units it has opened and 
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then continue to signal the error condition. Typically, this is done 
for the QUITS condition, signaled when the user types OQNTROL-P or 
BREAK. 

Note, however, that although closing file units upon recognition of the 
QUITS condition has advantages, a distinct disadvantage is that the 
user cannot restart your program by issuing the START command. If the 
user attempts this, the program continues executing where it was 
stopped until it attempts to use one of the closed file units. At this 
point, an error indicator is returned to the program. 



FILE ATTRIBUTES 

PRIMOS maintains a set of file attributes for every file, segment 
directory, file directory, and access category on disk. The file 
attributes of a file system object can be read and written by a user 
program that frg^ sufficient access to the parent directory of the 
target object. File system attributes include: 

• The date and time the object was created 

• The date and time the object was last accessed 

• The date and time the object was last modified 

• The date and time the object was last backed up 

• The read/write lock of the object 

• The file type (which once established can only be read) 

• The dumped/not dumped state of the object 

• The special/not special state of the object (which is set at 
disk initialization and can only be read) 



Note 

The date and time created (dtc) and date and time last accessed 
(dta) attributes may appear in directory entries beginning at 
PRIMOS Rev. 20.0. These expanded entries are accessed through 
the use of a hash table. At Rev. 20.0, MAKE creates all 
directories as hashed ACL directories unless an option is 
specified that creates a pre-Rev. 20.0 disk. A Rev. 20.0 
system can use pre-Rev. 20.0 disks, as can a pre-Rev. 20.0 
system. A system running pre-Rev. 20.0 PRIMOS can not use 
local Rev. 20.0 disks, but it'can use remote Rev. 20.0 disks. 
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The Date and Time Last Accessed (DTA) Attribute 

The date and time last accessed (dta) attribute of a system object or 
its parent is modified under various circumstances as depicted below. 



Action Result 

Object DTA Parent DTA 
Modified? Modified? 

Close an open entry (from read or write) 
Segment directory subfile 
After read from write-protected disk 
Write attribute 
dump 
dtm 
dtb 
dtc * 
dta * 

other (delete switch, protection, 
rwlock, logical type, truncated bit) 
Read any attribute 
Tape backup (MAGSAV) 
Tape backup (BRMS) * 
Tape restore (MAGRST - 

Set to time of restore) 
Tape restore (BRMS) 
Size 
Remote size 

Pre-Rev. 20.0 system operating on 
Rev. 20.0 hashed directory 
Remote backup (MAGSAV) 

Pre-Rev. 20.0 system operating on 
Rev. 20.0 hashed directory 
Remote backup (BRMS) 

Pre-Rev. 20.0 system operating on 
Rev. 20.0 hashed directory N N 



Dta and dtc can be set only by members of the user group 
named .BACKUPS. Backups performed by this group are 
recorded in the date and time last backed up (dtb) 
attribute. 



Y 


N 


N 


Y 


N 


N 


N 


N 


N 


N 


N 


N 


N 


Y 


N 


N 


N 


Y 


N 


Y 


Y 


N 


N 


N 


Y 


N 


N 


N 


N 


Y 


N 


Y 


Y 


N 


Y 


N 


N 


N 


N 


N 



Second Edition 1-32 



HOMOS FILE SYSTEM CONCEPTS 



Format of the Date and Time Last Accessed. Attribute : The format of the 
dta attribute of a file system object is declared in PL/I as follows: 



del 1 dta, 

2 date, 

3 year bit(7), /* Starting in year 1900. */ 

3 month bit (4), /* January is month 1. */ 

3 day bit(5), /* The first day of the month is day 1. 

2 time fixed bin(15); /* (Seconds since midnight)/4. */ 



As shown in this declaration, the dta attribute occupies one fullword, 
or two halfwords. The first halfword is organized as follows: 



YYYYYYYMMMMDDDDD 



Here, YYYYYYY is the year minus 1900, MMMM is the month (January is 
month 1), and DDDDD is the day of the month. 

The second halfword is the number of seconds past midnight divided by 

four. The remainder portion of the result of the division is 

discarded. Therefore, the granularity of the dta field is four 
seconds. 



The Date and Time Created (PTC) Attribute 

The date and time created (dtc) attribute contains the date and time 
that a file system object was created. 



Format of the Date and Time Created Attribute : The format of the dtc 
attribute of a file system object is the same as that for the date and 
time last accessed attribute. 



The Date and Time Last Modified (DIM) Attribute 

Whenever a change occurs in the file system data or structure, the date 
and time last modified (dtm) attribute of the file system object 
involved is set to the current date and time. User programs may use 
the dtm attribute of file system objects to determine when the objects 
were most recently modified. 

User programs may also change the dtm attribute of a file system object 
to any date and time. 
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How PRIMOS Sets the Date and Time Last Modified Attribute: The 



dtm 



attribute of a file 
type, as shown below. 



system object is set depending upon the object 



Type 
file 



segment 
directory 



file 
directory 



access 
category 



DTM Attribute Set 

when the file is first created, and whenever the 
file is closed after data in the file has been 
modified or after the file has been truncated. 
(The dtm attribute of a file is not changed when 
any other attributes of the file are changed.) 

When the segment directory is first created, and 
after the segment directory is closed when any of 
its members have been created, deleted, modified, 
truncated, or renamed, or when its size is 
changed. 

When the directory is first created, when one of 
its members is created, deleted, or renamed, or 
when certain attributes of one of its members are 
changed by a user program. Changes to all 
attributes except the dumped bit, the date and 
time last modified, and the date and time last 
backed up cause the updating of a parent 
directory's dtm field. The parent directory's dtm 
field is also updated when the access control for 
one of its members is changed. 

When the access category is first created, or when 
its contents are changed. Changing the contents 
of an access category does not, however, update 
the date and time last modified field of any 
objects protected by that access category. 



The purpose of the dtm attribute is to record the change of any file 
system data or structure somewhere in the file system itself. Thus, 
creating a new file sets the dtm attribute for both the file and its 
parent directory. Subsequently deleting the file will also update the 
dtm attribute for its parent directory. Although the net result may be 
that the contents of the directory are unchanged, the recent dtm 
attribute of the parent directory is an indicator that activity has 
taken place within the directory. 



Format of the Date and Time Last Modified Attribute : The format of the 
dtm attribute of a file system object is the same as that for the date 
and time last accessed attribute. 
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The Date and Time Last Backed Up (DTB) Attribute 

The date and time last backed up (dtb) attribute contains the date and 
time that a file system object was last backed up by a member of the 
BACKUPS group. 



Format of the Date and Time Last Backed Up Attribute : The format of 
the dtb attribute of a file system object is the same as that for the 
date and time last accessed attribute. 



The Read/Write Lock Attribute 

One of the responsibilities of the PRBOS file system is to ensure 
against attempts by several user processes to read and write one file 
simultaneously. For example, if user FRED opens a file for reading and 
writing, user BARNEY will be unable to open the file until user FRED 
has closed it. 

Some applications require this restriction to be lifted. For example, 
an application might require several users to have a file open for 
writing at the same time. The FRIMDS file system allows this to be 
specified via a read/write lock attribute. 



The Nature of the Read/Write Lock Attribute : Every segment directory 
and file has a read/ write lock attribute. File directories and access 
categories do not have them, since FRIMOS is entirely responsible for 
synchronizing updates to these objects. 

A file is protected against concurrent access by its read/write lock. 
The read/write lock attribute for a file is checked every time a user 
opens the file for reading, writing, or both reading and writing. In 
addition, a check is made to see if the file is already open for 
reading and/ or writing. Depending on the results of these two checks, 
the attempt to open the file may be rejected with the error code e$fius 
(File in use). 

Even if only one user is accessing a file, that user may receive a 
file-in-use error if he or she attempts to open the file twice. PRIMOS 
does not distinguish between two different processes attempting to open 
a file and one process attempting to open a file on different file 
units. For example, if a user attempts to open one file for writing on 
two different file units, the second attempt to open the file may fail. 



Segment Directories and the Read/Write Lock Attribute : The read/ write 
lock attribute for a segment directory affects not only the segment 
directory itself, but also serves as the read/ write lock for all of its 
members since segment directory members have no attributes of their own 
(except for file type). 
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However, FRBOS still distinguishes between the segment directory and 
each of its members when it is called upon to open the directory or its 
members. Therefore, two users may have two different files within one 
segment directory open for writing at the same time, whereas an attempt 
by a user to open a segment directory member file that is already open 
may meet with, failure. 



The Format of the Read/Write Lock Attribute : The format of a 
read/ write lock attribute is as follows: 



del rwlock bit (2); 



The four possible values for a read/write lock attribute are as 
follows: 



Value Keyword Meaning 

SYS Use the system-wide default. The system 

default is set via the RYTLOCK configuration 
directive, as described in the System 
Administrator's Guide , Vol. I. Normally, 
the default is 1, corresponding to a file 
read/write lock of 1, or EXGL (described 
below). 

However, the system-wide read/ write lock 
may be 0, meaning only 1 reader or 1 writer 
may have a file open at a time. The other 
possible value for a system-wide read/write 
lock is 3, corresponding to a file 
read/write lock of 2, or UEDT (described 
below). 

1 EXGL Exclusive control; n readers or 1 writer. 

This allows multiple processes to read a 
single file at a time, unless the file is 
being written. If the file is being 
written, no other user may open the file. 

2 UEDT Update control; n readers and 1 writer. 

This allows multiple processes to read a 
single file at a time even while it is 
being written by one process. It still 
prevents more than one process from writing 
to the same file at the same time. This 
setting is useful for command output 
(GOMOUTFUT) files, for example. 
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Value Keyword Meaning 

3 NONE No control; n readers and m writers. This 

provides no locking on a file at all. 
Using this setting is not recomraended, as 
it decreases the performance of the file 
system, and can result in damage to your 
files. 



The File Type Attribute 

Every object in the FRIMOS file system has a file type . File types 
include the following: 

• Sequential access method file (SAM) 

• Direct access method file (DAM) 

• Contiguous access method file (GAM) (for ROAM files only) 

• Sequential access segment directory (SEGSAM) 

• Direct access segment directory (SEGDAM) 

• File directory 

• Access category (AGAT) 

The file type of an object is determined only when the object is 
created. * It cannot be changed afterwards without deleting and 
recreating the object. 

The file type of an object can be read by a user program along with 
other file system attributes. The file type attribute is declared as 
follows: 

del type bit(8); 

The seven possible values, and their correspon din g keywords, are: 

Keyword Value 



SAM 





DAM 


1 


SEGSAM 


2 


SEGDAM 


3 


Directory 


4 


ACAT 


6 


CAM 


7 (ROAM files only) 
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Notice that file type value 5 is not defined. A value of 5, and any 
other undefined value, should be treated as an unrecognized file type. 
Prime reserves the right to use any or all of these undefined values. 



The Dumped/Not-dumped Attribute 

For backup service, the file system provides a dumped bit for all file 
system objects except access categories. The file system resets this 
bit whenever the corresponding object is modified. A backup utility 
can read the dumped bit to determine whether to make a backup copy of 
the object. If the dumped bit is reset, the utility can then make a 
backup copy, and set the dumped bit on for the object. 

The dumped bit for a file system object is reset (turned off) whenever 
the dateand tine last modified attribute for the object is updated. 
Similarly, if a file is deleted or renamed, the dumped bit of the 
parent directory is reset when the dtm attribute of the parent 
directory is updated. 



Dumped Bits for Directories : When a file is modified, the resetting of 
dumped bits is not performed on all of the directories that intervene 
between the file and the MFD. Therefore, a backup program must walk 
through the entire contents of a directory, sensing the dumped bits for 
all of its members, before deciding that no recent modifications have 
been made to its members. 



Dumped Bits for Segment Directories : File attributes exist only for 
members of file directories. Therefore, when a file within a segment 
directory is modified, the resetting of the dumped bit occurs on the 
parent segment directory, and not on the file, because the parent 
directory is a member of a file directory, and the individual files are 
not. 

Therefore, only the top-level segment directory dumped bit need be 
tested to determine whether the contents of the segment directory have 
changed. 

A corollary is that if the dumped bit for a segment directory is reset, 
the entire segment directory must be backed up, even if only one member 
of the segment directory has been modified. 



The Special/Not-special Attribute 

User programs that read directory entries may find the special bit 
useful. PRIMOS sets this bit on for all of the special files when it 
creates a new disk partition. Special files include the MFD, the BOOT 
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file, the BADSPT file (if it exists), and the record allocation table 
for the disk partition (which has the name of the disk partition as its 
objectname) . 

PRIMOS does not allow user programs to change the special bit for a 
file system object, nor does it allow objects with the special bit set 
to 1 to be deleted. 

Special files exist only in the MFD for a disk partition. 



QUOTAS 

PRIMOS allows you to set quotas on your directories and lower-level 
directories under certain conditions. Your programs can also make use 
of quota manipulation subroutines to do this. Quotas are expressed in 
terms of numbers of physical disk records, and must be assigned 
carefully if they are to be meaningful and useful. 

Detailed explanations of quotas and their settings can be found in the 
System Administrator's Guide , Vol. I, and in the Prime User's Guide . 
Subroutines related to quotas are described in Chapter 9, DISK QUOTAS, 
and in the Subroutines Reference Guide, Vol. II. 
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2 



Programmer Interfaces 
to the File System 



COmpter 1, PRIMOS FILE SYSTEM CONCEPTS, introduced you to the concepts 
of the file system you will need to know in writing programs that deal 
with files, access categories, and the various kinds of directories 
that the file system supports. 

This chapter will explain the file system interfaces that you as a 
programmer can use to communicate with the file system, what these 
interfaces allow you to do, and the principles involved in using them. 



OOMMmTICATING WITH THE FILE SYSTEM 

As a programmer using PRIMOS programming tools like editors, compilers, 
and linkers, you have at your disposal a number of procedures by which 
you can cxjmmunicate with the file system. From your terminal you can 
use commands to attach to directories, set access to file system 
objects, and create, open, close, and delete file system objects. 
These commands invoke PRIMOS programs that in turn call subroutines 
that perform the requested functions. Some PRIMOS programs invoke 
command functions, which in turn invoke subroutines to do their tasks. 



Commands 

Commands constitute the highest-level programmer interface to the 
PRIMOS operating system. This is the interface that you use to request 
the execution of PRIMOS programs stored in the standard command 
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directory CMDNCO, and to execute any application program you have 
developed and installed in this directory. Descriptions of all PRIMOS 
commands are given in the PRIMOS Commands Reference Guide . You or 
someone in your organization will provide information on the execution 
of your application programs. 

You can also request the execution of a program stored in a directory 
other than CMDNCO by invoking the RESUME command, supplying the 
pathname of the program as an argument. 



Command Functions 

Command functions can be considered the second highest -level programmer 
interface after the command level. Command functions are used in a 
PRIMOS command line, and are analogous to subroutine calls in a 
program: during program execution, a subroutine call in a program 
statement requests the service of a precompiled procedure stored in a 
subroutine library; a command function requests the execution of a 
precompiled procedure at PRIMOS command level. A command function 
consists of a function name and zero or more arguments or options, all 
enclosed in square brackets ([ ]). It differs from a command in that 
it can return a value and store it in a variable for use by a 
subsequent command or command function. Command functions are 
explained in the PRIMOS Commands Reference Guide and the CPL User's 
Guide . 

For repetitive operations at command level, you can build a series of 
commands and command functions into a Command Procedure Language (CPL) 
file. You can store a CPL program in one of your directories and 
execute it by invoking it from PRIMOS command level using the RESUME 
command (for detailed explanations, see the CPL User ' s Guide ) . 

You can also store CPL programs in CMDNCO and invoke them directly as 
commands. However, for all but the simplest of routines, a CPL 
program's execution speed tends to be slower than that of the 
equivalent program stored in compiled form. 



Subroutine Calls 

As described in Chapter 1, PRIMOS FILE SYSTEM CONCEPTS, your 
application programs can contain subroutine calls that perform a 
variety of functions involving the file system: opening and closing 
files, reading and writing data, as well as a number of operations 
involving pathnames, access control, and the like. You can make use of 
the extensive library of Prime-supplied subroutines, but you can also 
create your own libraries of subroutines tailored to the needs of your 
applications. Commands and command functions make extensive use of 
Prime-supplied subroutines during their execution; for example, the 
editor program uses subroutines to open, read, write, and close text 
files, as well as to create new files when necessary. These operations 
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implicitly involve other subroutines that may, among other things, 
attach to top-level directories, evaluate access rights, and supply 
access control lists for newly created files. All of these actions are 
largely invisible to you as you sit at your terminal running the 
editor, unless you attempt to violate an access right, or ERIMOS 
detects some kind of abnormal condition such as a directory quota 
overflow. 



System Primitives 

As you have no doubt inferred, subroutine calls are not necessarily 
single-level operations, but may progress to one or more sublevels. 
There is a point at which no further sublevels are called during a 
subroutine's execution. A subroutine that itself makes no calls to 
other subroutines is known as a system primitive ; it is the lowest 
programmer-visible interface between a program and PRIMOS. The PRWF$$ 
subroutine, for example, is a system primitive that positions, reads, 
writes, or truncates a file; it can be called directly from a program, 
or indirectly through other subroutines such as SRCH$$ (used to open, 
close, delete, change access, or verify the existence of a file). 



Arguments and Options 

Arguments and options are additional elements of all of the programming 
interfaces described so far. They increase the flexibility of 
operations of commands, command functions, and subroutines by allowing 
variations in the ways in which they operate. An argument is usually a 
character string that defines the object to be operated on, such as a 
filename, a directory name, a file unit number, or one of the several 
forms of pathname. An option defines the way the object is operated 
on. 

For a call to the SRCH$$ subroutine, for example, an argument would be 
the name of a file unit to be operated on, and an option could specify 
that the desired action is to open the file unit. Another option could 
specify whether the file unit was to be opened for reading, writing, or 
both. A subsequent call to SRCH$$ would be used to close the file 
unit, using the same file unit number (argument) and a different action 
(option) . 

For example, to open a new DAM file for writing on an unused file unit, 
perform some write operations on it, and then close it, you could use 
the following sequence of calls: 

CALL SRCH$$(K$WRIT+K$GETU+K$NDAM, NEWFILE, 7, UNIT, TYPE, CODE) 

. Do some write operations 
CALL SRCH$$(K$CLOS, 0, 0, UNIT, 0, CODE) 
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The three K$ options in the first call specify opening a DAM file 
(K$NDAM) for writing (K$WRIT) on an available file unit (K$GETU). The 
K$CLOS option in the second call causes the file to be closed. UNIT is 
a data element defined in the program to receive the file unit number 
returned by the subroutine when it opens the file; it also specifies 
the file unit to be closed. The zero (0) entries in the close call 
indicate that space must be reserved in the calling sequence for all 
elements of the call, even though some may be unused for certain 
actions. 

At command level, arguments and options are similarly used. For 
example the SET_AOCESS command accepts both an argument to specify the 
name of the object on which the access control list is to be set , and 
an option to specify whether the list is to be obtained from an access 
category or set the same as another (existing) object. 



Attach Points and Access Rights 

All of the programming interfaces to the file system assume that you as 
a programmer at a terminal, or a user using one of your programs, can 
access the object or objects to be worked on. That is, the user-id of 
the person working on an object must exist (either explicitly or 
implicitly) on that object's access control list (ACL), and the ACL 
must include, for that user-id, the kind of access appropriate to what 
the person wants to do. (Refer to the Projme User's Guide for details 
on access control lists.) 

In order to gain access to a file system object, you (or your program) 
must also be attached to the directory that either directly or 
indirectly (by way of one or more lower-level directories) contains the 
object . You can attach to a directory from your terminal at command 
level by using the ATTACH command; your program can do the same thing 
by using one of the ATS subroutine calls. In both cases, Use (U) 
access is required at all directory levels that have to be passed 
through to get to the object. 

The Three Attach Points : The initial, home, and current attach points 
identify your (or your user's) initial, home, and current directories. 
Other terms refer to these attach points as follows: 

• The initial attach point identifies the initial, origin, or 
login directory. 

• The home attach point identifies the home, or working directory. 

• The current attach point identifies the current directory. 

The terms attach point and directory are generally interchangeable. 
You establish an attach point by attaching to a directory. 
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The PRIMOS file system is heavily dependent on attach points. Most 
commands, command functions, and subroutines involving file access use 
the current attach point. Subroutines that accept pathnames to objects 
outside the home directory can temporarily change the current attach 
point during their execution. Some file system subroutines allow the 
attach points to be permanently changed. 



There are specific uses for 
points, summarized as follows: 



and restrictions on the three attach 



Attach Point 



Use 



Initial 



Attaches you to your initial directory. The 
initial attach point is established when you 
first log in. From the terminal, you can 
attach to your initial directory at any time by 
issuing the PRIMOS command ORIGIN. Your 
program can attach to the initial directory by 
a call to the AT$CR subroutine. 



Home 



Current 



Neither you nor any user program can change the 
initial attach point. This can be done only by 
a System or Project Administrator. 

Establishes and attaches you to your home 
directory. This directory is your primary 
working directory. From the terminal, you can 
change the home directory by using the ATTACH 
command; a program uses a call to the AT$HCM 
subroutine. Changing the home attach point 
also changes the current attach point.' When 
commands such as LD and LIST_QUCTA are issued 
without arguments, the home directory is the 
implicit target directory. 

User programs may change the home attach point, 
but this is rarely done except when it is part 
of the function of the program to do this. 

Establishes and attaches you to a current 
directory. The current attach point is 
normally the same as the home attach point. 
However, programs can change the current attach 
point by using one of the ATS subroutines to 
operate on objects outside the home directory 
without changing the home directory. Before 
returning the user to command level, programs 
should always reset the current attach point to 
the home attach point. 

Most PRIMOS subroutines that change the current 
attach point reset it to the home attach point 
before returning to their callers. 
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Attach Point Use 

Normally, you cannot explicitly, from command 
level, set the current attach point to be 
different from your home attach point. You 
can, however, explicitly reset the current 
attach point to he the same as the home attach 
point by issuing the ATTACH command with no 
arguments. 

Access Rights : There are currently nine access rights that PRIMOS uses 
at various times to determine whether you (as a programmer) or your 
program (on behalf of its user) can do what you or your program want to 
do with a file system object. These rights and what actions they allow 
are explained in detail in the Prime User's Guide . In brief: 

0: Applies to files and directories; allows user to set access 
rights except for P and ALL; if the object is a file or a 
segment directory, the possessor is permitted to set the 
rwlock. 

P: Applies to directories; allows the access rights and 
attributes of the directory and its subordinate objects to be 
changed. 

D: Applies to directories; allows subordinate objects to be 
deleted or renamed. 

A: Applies to directories; allows subordinate objects to be added 
or renamed. 

L: Applies to directories; allows their contents to be listed. 

U: Applies to directories; allows the directory to be "used;" 
that is, attached to or passed through on the way to a 
subordinate object. 

R: Applies to files; allows them to be read; allows EPFs to be 
executed. 

w: Applies to files; allows them to be written. 

X: Applies to local EPFs; allows them to be executed (not 
required if R is allowed). 

Two other rights, represented by the character strings ALL and NONE, 
mean, respectively that all of the above individual rights, or none of 
them, apply to the user to whom these designations are given. 
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An important point to remember, when referring to a program's access to 
a file system object, is that it is not the program that must have 
access to the object, but the user on whose behalf the program is 
running. That is, the user-id by which a user is known to the system 
must exist on the access control list of the object on which an action 
is to be performed. 

The ACL of a newly created object is always inherited from its 
containing directory. It is then said to have a default ACL. A newly 
created file or directory inherits all of the access rights of its 
parent directory (even though R, W, 0, and X accesses are the only ones 
meaningful to a file). If you change the inherited ACL of a newly 
created directory, then the changed ACL becomes the default ACL for any 
objects subsequently created within the new directory. 

The existence of the user-id on the ACL may be either explicit (the 
user-id itself) or implicit (the name of a group to which the user 
belongs or the special identifier $REST). Each of these has its uses 
in particular circumstances. For example, if you are writing a program 
that creates a file for the exclusive use of its user, it would be 
appropriate for that program to create for the file an ACL that 
contains the user's name explicitly, and gives him the necessary rights 
to the file. On the other hand, if the program executes on behalf of a 
data base group, and that group has a group-id, then it would be 
appropriate to crea + ^ an ACL that contains the group-id and the rights 
applicable to the group. Any fine-tuning of this ACL with respect to 
specific users in the group can be done by using the ACL-related 
commands from PRIMOS command level. 



Object Names 

The ways in which object names can be specified vary from command to 
command, command function to command function, and subroutine to 
subroutine. The allowable forms of object names (simple names, 
relative, full, or absolute pathnames) for the various levels of PRIMOS 
interfaces are defined in the appropriate manuals and guides. For 
subroutines that deal with the file system, they are given also in 
later chapters of this book. 

You must keep in mind, when writing application programs that use file 
system subroutines, that the way you specify an object name in a 
subroutine call (if you have a choice of method) can affect one or more 
of your attach points in some unexpected way. It may also determine 
whether or not the user on whose behalf your program is running has 
access to the object whose name is specified. Refer to the section 
titled HOW AND WHEN ACCESS IS CALCULATED in Chapter 1 , PRIMOS FILE 
SYSTEM CONCEPTS, and remember that the same subtleties of the ACL 
mechanism that apply at command level can also apply at the command 
function and subroutine levels. 

When interpreting object name arguments, subroutines make a distinction 
between home and current directories that is not made at command level 
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or command function level. For a subroutine, the current directory is 
the directory to which the process is currently attached. The home 
directory is either the one first attached to when the user logs in, or 
the one specified in a subroutine call such as AT$HDM. 

Assume, for example, that you have used the ATTACH command to attach to 
a directory MYDIR. Your home and current attach points are now MYDIR. 
Now, you invoke a command or program with a pathname as an argument: 



MYPROG JANESDIR>MEMOS 

The behavior of the home and current attach points is as follows: 

1. The home attach point remains the same; from your point of view 
the attach point does not change. 

2. MYPROG calls various subroutines that locate, check access, and 
open the MEMOS file in the JANESDIR directory. The subroutines 
change the current attach point to JANESDIR. 

3. When the program terminates, the last subroutine executed 
(typically the one that closes the file) sets the current attach 
point back to MYDIR. 

When you use a subroutine that accepts only a simple pathname, you must 
know the current attach point (and hence the current directory), 
because the current directory is the one that is used to determine the 
pathname of an object referred to by a simple name. 



File Units and Attributes 

When a file is opened using a subroutine call such as SRCH$$, it 
becomes associated with a file unit number, which is used in subsequent 
subroutine calls to manipulate the file data. A file can be read or 
written only by referring to its file unit number in read or write 
subroutine calls. File units are described more fully in the 
Subroutines Reference Guide , Vol. II. 

Files can be opened by specifying a file unit number explicitly or by 
allowing PRIMOS to allocate one (except in the FORTRAN language, which 
requires an explicit file unit number). If you are writing a program 
that is entirely self-contained (that is, it does not support, require 
support from, or otherwise communicate file information to another 
program) , it makes little difference how you associate a file with its 
file unit number, other than to make sure that an explicitly defined 
number is not already in use by the same program. However, if your 
program is one element of a larger group of programs that make up a 
subsystem and that have to communicate file unit information among 
themselves, then it is more appropriate to let PRIMOS allocate file 
unit numbers, and to have the program that opens the file the first 
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time store the returned file unit number in a program variable 
accessible to all components of the subsystem. This technique is 
particularly appropriate when a number of file units are opened at 
various times and in unpredictable order. 

In programming a subsystem, once a file has been opened for the first 
time and associated with a file unit number, then that number should be 
used for all subsequent operations on that file, using the centrally 
stored file unit number returned from the first open call. In 
particular, if the same file is opened more than once during an 
application's execution, the file unit number resulting from the first 
open call should be used to explicitly define the number for subsequent 
open calls, rather than letting FRIMOS allocate a possibly different 
number and cause inconsistencies to arise among the members of the 
family of programs in the subsystem. 

when your program has opened a directory containing a file system 
object, a set of attributes describing each object contained in the 
directory is available to the program. The attributes are read by the 
ENT$RD subroutine call into a structure that your program provides, as 
described in detail in Chapter 8, FILE ATTRIBUTES. 

You must remember two things when using a subroutine that reads, sets, 
or cha n ges the attributes of an object. First, the containing 
directory must be open and associated with a file unit number, since 
this is the argument that the subroutine uses to determine which 
directory to look in for the attribute list. Second, the object whose 
attributes are to be obtained, set, or changed must be immediately 
contained within that directory, since the argument specifying the 
object's name does not accept a pathname (that is, the object is 
assumed to be in the current directory). 

The subroutine used to set or change attributes is SATR$$, which is 
fully described in the Subroutines Reference Guide , Vol. II, along with 
the formats of the structures that your program needs to provide for 
its operation. 



FRIMOS Responses (Return Codes) 

Virtually all FRIMOS subroutines communicate with their callers in one 
consistent respect: they return a numeric code that informs the caller 
of the subroutine's success or failure in performing its task. For 
consistency, subroutines that you write for your own applications 
should also follow this practice. 

FRIMOS subroutines always place the return code in a 16-bit binary 
integer data item. If the subroutine was entirely successful in 
completing its requested function, the value of this integer is always 
zero (0). Other values are returned in case of total failure or 
partial success. Your program should always check the value of the 
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return code upon returning from a subroutine call and take whatever 
action is appropriate to the reported condition. 

A complete list of FRIMOS subroutine return codes is provided in the 
Subroutines Reference Guide , Vol. II, with some examples of how a 
program might respond to a nonzero response code. 

It is important that a subroutine call that can potentially change the 
current attach point be handled carefully when a nonzero code is 
returned. In order that the programmer can rely on some consistent 
current attach point even if a subroutine fails, most PRIMOS 
subroutines cause the current attach point to be set to the home attach 
point before returning to their callers, regardless of where the 
current attach point was before the call. Any programs, command 
functions, or subroutines that are to become part of a larger subsystem 
should handle nonzero return codes in a consistent way, and should be 
documented accordingly. 



FILE SYSTEM OPERATIONS : AN OVERVIEW 

This section gives you an overview of the five major operations 
(creating, opening, reading, writing, and deleting) that your programs 
can perform on file system objects and the general requirements that 
must be satisfied in order to do these operations. They will all be 
explained in more detail in subsequent sections. 



General Requirements 

In order to perform operations on file system objects, the users of 
your programs must be able to attach to the appropriate directories, 
and, in order to do this, they must have rights appropriate to what 
they want to do. A successful attach to a directory requires that the 
user have Use access to all directory levels from the MFD down to the 
level that contains (or will contain) the object. Additional rights 
required on the directory immediately containing the object depend on 
the action that is to be performed. For example, in order to change 
the name of a file, its owner must have both Add and Delete access to 
the directory containing the file. 



Creating Objects 

Programs that operate on files contain calls to subroutines that locate 
the files to be operated on, either in the user's home directory or in 
the current directory. If the attempt to locate a file that is to be 
opened for writing, or for both reading and writing, is unsuccessful, 
you can give the program the option of creating it in whichever 
directory it was being ' searched for. You do this by supplying a key 
that specifies the type of file to be created if it is not found. Your 
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program can also create lower-level directories by rising the sane 
subroutine calls with, the appropriate keys. Creating a new top-level 
directory requires a different subroutine from that which creates 
lower-level directories and files. 

If a search for a file for reading is unsuccessful, the subroutine 
returns an error code; the program must decide how to handle this 
condition. It is fairly probable that the file is not found because 
the program is attached to a directory other than the one in which the 
file is expected to exist; in this case the user is most likely 
expected to have attached to the proper directory from PRIMOS command 
level before executing the program. However, if the application can 
expect that a file to be read may not exist, then it should, by means 
of the appropriate key, test for the file's existence, inform the user 
in some meaningful way of its nonexistence, and provide for a graceful 
escape from the situation. 



Opening Objects 

Your programs open file system objects by using calls to any of several 
subroutines, depending on where the object is relative to the home 
directory, what kind of optional actions are desired (for example, 
creating new objects or retrying in case of initial failure), aM 
whether your applications are more suited to using system library 
subroutines or application library subroutines. The Subroutines 
Reference Guide , Vol. II, contains a chapter of all of the subroutines 
you can use to open file system objects. 

In general, the subroutines in the application libraries (APPKEB or 
VAPPLB) are easier to use for application programs, as their user 
interfaces are comparatively simple and they return codes that are 
either true or false. In many cases, these subroutines call 
lower-level subroutines, taking care of supplying arguments with which 
you as a programmer need not concern yourself. They also perform all 
possible error detection and recovery tasks before returning to their 
callers, thus ensuring that everything that can be done to complete the 
requested function is done, and that whatever errors are encountered 
are reported. 



Reading Objects 

Assuming that your program has successfully opened an object for 
reading or for reading and writing, the object can then be read, using 
any of several subroutine calls. The call to be used depends on 
whether the object is a file, a file directory, or a segment directory; 
there are also calls intended expressly for reading ASCII text files, 
getting characters or lines of text from command files or from the 
terminal, and getting characters from an array. 
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Positioning an object involves an Implied read of the object, although, 
no data is actually transmitted. Calls to position an object can be 
made either with a specified absolute position or with a position 
relative to the current position, either backward or forward. An 
object can also be positioned at its beginning or end. 

Writing Objects 

Assuming that your program has successfully opened an object for 
writing or for reading and writing, the object can then be written, 
using any of several subroutine calls. Generally, the writing of data 
files is done by explicit calls to write a line to a text file, a data 
file, or a command output file or terminal. You can also call a 
subroutine whose function is to store characters into an array. 

The writing of other file system objects (file and segment directories 
and access categories) is done implicitly during many operations on 
files. File creation, ACL manipulation, and file renaming, for 
example, all implicitly involve writing to these objects, but there are 
no explicit subroutine calls that result in writing a specific 
character or string to them. 

Files can be positioned to any arbitrary point before writing data to 
them. Normally, when additional data is written to a SAM or DAM file, 
the file is positioned to its end before writing is done; if the 
position is somewhere within the file (or at its beginning) , existing 
data will be overwritten. Indexed files, such as those used by 
MIDASPLUS, are capable of having records inserted into them; such 
subsystems take care of insertions in such a way as not to overwrite 
existing data. 



Deleting Objects 

Several subroutines are available to delete files and directories; the 
one you choose will usually depend on whether the object is directly 
contained in the home directory or elsewhere. 

The ability of your program to delete an object depends on the user's 
access rights not only on the object itself but also on the parent 
directory. The state of the delete-protect attribute on the object 
also affects the user's ability to delete an object, independent of 
access rights. The ability to set or reset this attribute, in turn, 
depends on the user's having Protect rights on the parent directory. 

Having given you an overview of the programmer's interfaces to the file 
system and the kinds of things that can be done with file system 
objects, the rest of this chapter gives more details on file system 
operations at the command level and at the subroutine level. 
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ACCESS CONTROL TO FILE SYSTEM OBJECTS 

This section describes the requirements and procedures for attaching 
and controlling access to file system objects, both at command level 
and at the subroutine level. 

As previously described, only file directories can be attached to; you 
cannot attach to segment directories, access categories, or files 
directly, but you can attach to the file directories that contain any 
of these objects. 



Attach/ACL Requirements 

Your user-id, or that of your program's user, must appear at all 
directory levels above the directory that is being attached to, and the 
access rights must include Use access. The user-id can be explicit, or 
it can be Implied as the member of a specific group-id or the special 
group $REST. Use access can be specified explicitly (U access) or 
implicitly (ALL access). 

Access control lists and the subroutines for manipulating them are 
described more fully in Chapter 7, ACCESS CONTROL LISTS (ACLS). 



Attaching 

At the command level you can attach to two of the three kinds of attach 
points: the home attach point and the initial, or origin, attach 
point. Remember that the initial attach point, the point at which you 
are attached when you first log in, cannot be changed except by your 
System Administrator or Project Administrator. You can change your 
home attach point, however, at any time; in fact, if the files you are 
working on (specifically, program files if you are a programmer) are in 
a directory other than your initial directory, you should use Attach 
commands to attach to the directory containing them. 

At the subroutine level, your programs can set not only the initial and 
home attach points, but also the current attach point, a (usually) 
temporary attachment that is in effect only for the duration of the 
routine in which the subroutine is called. 



ATTACH TO INITIAL DIRECTORY 



Command Command Function Subroutine 



ORIGIN None AT$OR 
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Attach to Initial Directory (Command) : To attach to the initial, or 
origin, directory from PRIMOS command level, use the command: 



ORIGIN 



Using the ORIGIN command sets both the home and the current attach 
points to the Initial directory. The ORIGIN command requires no 
arguments. 

Attach to Initial Directory (Command Function) : There are no command 
functions that explicitly set the attach point to any directory. 
However, some command functions, such as OPEN_FILE, could implicitly 
attach temporarily to the initial directory. A CPL program that needs 
to attach specifically to the initial directory can use the ORIGIN 
command as one of its statements. 

Attach to Initial Directory (Subroutine) : To attach to the initial 
directory from a program, use the subroutine call: 

AT$OR (key, code) 

The value of key_ is K$SETH if both home and current attach points are 
to be set to the initial directory, or K$SETC if only the current 
attach point is to be set. 

Note that if only the current attach point is set, any subroutine that 
uses a simple object name as an argument will look in the initial 
directory for the object, regardless of the setting of the home attach 
point. 

The details of the calling sequence for the AT$OR subroutine are given 
in Chapter 4, ATTACH POINTS. 





ATTACH TO HOME DIRECTORY 


Command 


Command Function Subroutine 


ATTACH 


None AT$HOM 



Attach to Home Directory (Command) : To define and attach to the home 
directory from PRIMOS command level, use the command: 

ATTACH [directoryjiame] 
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Using the ATTACH command sets both the home attach point and the 
current attach point to the directory specified as the argument. If no 
argument is given, no change occurs (unless the current attach point 
has been left set at some other point in a previous operation, in which 
case it is reset to the home attach point). 

The directory_name argument can be any form of pathname that leads to a 
file directory. 



Attach to Home Directory (Command Function) : There are no command 
functions that explicitly set the attach point to any directory. A CPL 
program that needs to specifically set the home directory can use as 
one of its statements the ATTACH command in the form just described. 

Attach to Home Directory (Subroutine) : To set the current attach point 
to the current home directory from a program, use the subroutine call: 



AT$HOM (code) 



The details of the calling sequence for the AT$HOM subroutine are given 
in Chapter 4, ATTACH POINTS. 





ATTACH TO ANY DIRECTORY 




Command 


Command Function 


Subroutine 


ATTACH 


None 


AT$ 
AT$ABS 
AT$ANY 
AT$REL 



Attach to Any Directory (Subroutine) : To set the current and 
(optionally) the home attach points to a specific directory (other than 
the initial or home directory), use one of the following subroutine 
calls: 



AT$ (key, path, code) 

AT$ABS (key, partition, directory, code) 

AT$ANY (key, name, code) 

AT$REL (key, name, code) 



Details of these calling sequences and their operations are given in 
Chapter 4, ATTACH POINTS. 

In all of these calls , the value of key determines whether both the 
current and home attach points are to be set, or only the current 
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attach point. A value of K$SETH sets both; a value of K$SETC sets 
only the current attach point. If you specify K$SETH, the effect is 
the same as if the ATTACH command had been used at the terminal. 

The AT$ call is the most general of all of the attaching calls, in that 
it accepts a pathname in any form, and then calls one of the others, 
depending on the results it obtains from parsing the pathname. A null 
name argument (' ') means the home directory, and is equivalent to the 
AT$H3M call or the ATTACH command with no argument. You can use the 
AT$ call to attach to anywhere from anywhere, regardless of whether or 
not the current and home attach points were the same before the call. 

In the AT$ABS call, partition is the name or logical disk number of an 
active disk on the system on which your program is running, or on 
another system connected through a network. The partition argument can 
also be the null string, implying logical disk tzeroTi "or it can be 
' * ' , signifying the disk partition containing the directory to which 
the current attach point is set at the time of the call. 



The directory argument is the name (and optional directory password, 
separated by a single space) of a top-level directory on the disk 
partition identified by partition . A null directory argument signifies 
the MFD of the disk partition. 

The AT$ANY call requires name to be a full pathname, beginning with the 
name of a top-level directory. Remember the rules that were given in 
Chapter 1, PRIMOS FILE SYSTEM CONCEPTS, for directory searching when 
using a full pathname. 

The AT$REL call requires name to be the name of a directory immediately 
subordinate to the current directory. It can include a directory 
password, separated by a single space. 



Access Control List (ACL) Functions 

The ACL functions can be used at the command level to define, modify, 
list, and delete user access rights on file system objects. You can 
define ACLs by default from the object's containing directory, by 
specifying separate user-ids and their individual rights, or by 
specifying user groups and the rights that apply to them. You can also 
define access categories that protect any number of objects with the 
same ACL. The PRIMOS Command Reference Guide and the Prime User's 
Guide explain the use of the various ACL-related commands in detail. 

When using ACL-related subroutines in a program, your program must 
furnish the ACL entries in the form of a structure containing the 
user-id/ access-right pairs; the subroutine call supplies the address 
of the structure in the form of a pointer argument, addr(acl_struct) . 
Chapter 7, ACCESS CONTROL LISTS (ACLS), gives the details of the 
calling sequences and operations of all of the ACL-related subroutines. 
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The ACL structure is shown pictorially in Chapter 7, ACCESS CONTROL 
LISTS (ACLS), and in program declaration form in the Subroutines 
Reference Guide . Vol. II. 

The target object for any ACL-related command or subroutine can be a 
file, a file directory, or a segment directory. An access category is 
a special object that contains an ACL used to protect other objects; 
the ACL of the access category itself is the same as that of the group 
of objects it protects. 

At both command and subroutine levels you, or your program's user, must 
have Protect and List access to the containing directory, and Protect 
access to the object on which an ACL is to be set. 







SETTING DEFAULT ACCESS 




Command 


Command Function 


Subroutine 




SETJWXESS 
SAC 


None 


AC$DFT 



Setting Default Access (Command) : PRIMOS gives a default ACL 
automatically to any object whenever the object is created; the ACL is 
the same as that of the containing directory. (The System 
Administrator or Project Administrator should set a specific ACL, as 
described later, on a top-level directory if it is to be different from 
that of the MFD. ) Any objects created at levels below the top-level 
directory will then get this specific ACL by default. 

To set a default ACL from PRIMOS command level, use the command: 



SET_ACCESS objectname 
SAC 



In this form of the SET_ACCESS command, if the target object has an ACL 
different from the default, its ACL will be reset to the default. A 
message may be returned indicating that there is already an ACL set on 
the object and asking whether it is to be replaced; the message can be 
suppressed by using the -NOJ$CIERY option. 

Be careful, when you set the default access on an object, that the 
directory that is supplying the default ACL has rights appropriate to 
the object on which, the default is being set. For example, Read and 
Write access as such, are not meaningful to directories, but are usually 
included in directory ACLs so that they will be inherited by 
subordinate files automatically. 
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Setting Default Access (Command Function) : There are no command 
functions to set access control lists. A CPL program that needs to set 
an ACL can use the appropriate FRIMOS command as a program statement. 

Setting Default Access (Subroutine) : To set a default ACL from a 
program, use the subroutine call: 

AC$DFT (name, code) 



The name argument can be any of the valid forms of pathname. The same 
precautions regarding propagated ACLs apply to the AC$DFT subroutine as 
to the SET_AOCESS command described above. 

Details of the calling sequence and its operation appear in Chapter 7, 
ACCESS CONTROL LISTS (ACLS). 



SETTING SPECIFIC ACCESS 



Command Command Function Subroutine 



SET_AOCESS I None AC$SET 

SAC 



Setting Specific Access (Command) : To set a specific ACL from FRIMOS 
command level, use the command: 



SET_AOCESS [ objectname user-id : access-rights . . . [-NOlQOERY] 
SAC 



In this form of the SET_ACCESS command, the resulting ACL contains the 
list of users and access rights given as arguments to the command, 
plus, by default, $REST:NQNE if no other specific rights are given to 
the $REST group. The ACL thus produced replaces any ACL already 
existing on the object. To modify an existing entry on an ACL without 
replacing the ACL, use the EDIT_ACCESS command, described later. 

If objectname does not exist , FRIMOS assumes that you want to create an 
access category. If you do, refer to Creating an Access Category , 
described later; otherwise answer NO to the query returned by FRIMOS. 

Setting Specific Access (Command Function) : There are no command 
functions to set access control lists. A CPL program that needs to set 
an ACL can use the appropriate FRIMOS command as a program statement. 
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Setting Specific Access (Subroutine) : To set a specific ACL from a 
program, use the subroutine call: 



AC$SET (key, name, addr(acl_struc) , code) 



In the AC$SET subroutine call, key^ governs the creation and replacement 
of ACLs and specifies the error to return if ACSSET is called to 
replace a nonexistent ACL or to create an ACL on an object that already 
has one. The AC$SET description In Volume II of the Subroutines 
Reference Guide lists the possible key values and their meanings. The 
name argument specifies the object that is to receive the new ACL, as 
in the ACSEFT call previously described. The structure of the ACL 
entries is shown in diagrammatic form in Chapter 7, ACCESS CONTROL 
LISTS (ACLS). Each entry can have as many as 80 characters, and there 
can be as many as 32 entries in a given list. 



SETTING CATEGORY ACCESS 



Command Command Function Subroutine 



SET_ACCESS None AC$CAT 

SAC 



Setting Category Access (Command) : To set the access of an object to 
that of an existing access category, use the command: 



SET_ACCESS I objectname -CATEGORY acatname 
SAC 



The objectname argument can be any valid form of pathname. The access 
category specified by acatname must exist in the same directory as that 
of the object being protected. (Creating an access category is 
described later in this section. ) 



Setting Category Access (Command Function) : There are no command 
functions to set access control lists. A CFL program that needs to set 
an ACL can use the appropriate FRIMOS command as a program statement. 

Setting Category Access (Subroutine) : To set the ACL of an object from 
a program, use the subroutine call: 

AC$CAT (name, category, code) 
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The name argument identifies the object to be protected; it can be any 
valid form of pathname. The category is the simple name of the access 
category that is to protect name ; the access category must exist and 
must reside in the same directory as name . The calling sequence and 
operation of the AC$CAT subroutine are described more fully in Chapter 
7, ACCESS CONTROL LISTS (ACLS). Access requirements for using the 
AC$CAT subroutine are described in the Subroutines Reference Guide , 
Volume II. 



SETTING ACCESS LIKE THAT OF ANOTHER OBJECT 



Command Command Function Subroutine 



SET_ACCESS 
SAC 



None AC$LIK 



Setting Access Like That of Another Object (Command) : To set an 
object's access so that it is identical to that of another object from 
PRIMOS command level, use the command: 



SET_AOCESS I objectnamel -LIKE objectname2 
SAC 



Both objectnamel and objectname2 can be any valid form of pathname; 
objects need not be in the same directory. The objectnamel argument 
identifies the target object on which the access is to be set; 
objectname2 identifies the object whose access is to be applied to the 
target object. 

There is also no requirement that source and target objects be of the 
same type. If the source and target objects are of different types 
(for example, the source is a directory and the target is a file), be 
sure that the source object includes access rights appropriate to the 
target, as described previously under Setting Default Access . 

When you use this form of the command, it does not matter whether the 
source object's ACL is derived from its superior directory, from an 
access category, or a specific ACL; the ACL of the target will always 
be a specific ACL, since it is the ACL's values that are copied, not 
the location of its source. 



Setting Access Like That of Another Object (Command Function) : There 
are no command functions to set access control lists. A CFL program 
that needs to set an ACL can use the appropriate PRIMOS command as a 
program statement. 
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Setting Aooess Like That of Another Object (Subroutine) : To set an 
object's access so that it is identical to that of another object from 
a program, use the subroutine call: 

AC$LIK (target, reference, code) 

Both, target and reference are any valid form of pathname; target 
identifies the object on which an ACL is to be set, while reference 
identifies the source of the ACL. The actions are the same as 
described in the command description just given; the calling sequence 
is described more fully in Chapter 7, ACCESS CONTROL LISTS (ACLS). The 
Subroutines Reference Guide , Vol. II gives information on the access 
rights required to use the AC$LIK call. 

CREATING AN ACCESS CATEGORY 



Command Command Function Subroutine 



SET_AOCESS I None AC$SET 

SAC | 



Creating an Aooess Category (Command) : To create an access category 
from FRIMOS command level, use the command: 



SET_ACCESS \ objectname user-id: access-rights 
SAC 



This is the same form of SET_ACCESS command as you use to set a 
specific ACL on an object, as described previously under Setting 
Specific Access . The difference is that, in this case, objectname 
identifies a nonexistent object, and FRIMOS assumes that you want to 
create an access category. PRIMOS tells you that the access category 
does not exist and asks whether you want to create it. If you do, the 
access category is created and given the name ob j ect name . ACAT and the 
specified ACL entry or entries. You can then use this access category 
in subsequent operations to set category access as described 
previously. 

Be careful, if you really want to create an access category, that the 
named object does not exist; otherwise, FRIMOS will locate the named 
object and apply the specified ACL entry or entries to it, with 
possibly unwanted results. If you know that an object whose name is, 
say, PRIVATE exists, you can still create an access category with the 
name PRIVATE. ACAT in the same directory by explicitly supplying the 
.ACAT suffix when giving objectname . FRIMOS will recognize this as a 
different object from PRIVATE, and will create the access category 
PRIVATE. ACAT. 
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The objeotname argument can be any valid form of pathname, implying 
that you can create an access category anywhere. Remember, though, 
that an access category must be in the same directory as the object(s) 
it is intended to protect. 

Creating an Access Category (Command Function) : There are no command 
functions to create access categories. A CPL program that needs to 
create one can use the appropriate FRIMOS command as a program 
statement. It would be prudent for your CPL program to test for the 
existence of the named object using the [EXISTS] command function 
before attempting to use the command to create an access category. If 
the function returns a result indicating that the object exists, it 
should allow the user to specify what to do. Refer to the CPL User's 
Guide for information on the [EXISTS] command function and how to query 
the user and request a response. 

Creating an Access Category (Subroutine) : To create an access category 
from a program, use the subroutine call: 

AC$SET (key, name, addr(aol_struc) , code) 



when using AC$SET to create an access category, name must identify a 
nonexistent object (any valid form of pathname), and key must have a 
value of either (zero) or K$CREA. As before, addr(acl_struc) is a 
pointer to an area in your program that contains the structure of the 
ACL to be set on the access category. 

The calling sequence and operation of the ACS SET subroutine are more 
fully presented in Chapter 7, ACCESS CONTROL LISTS (ACLS). The 
Subroutines Reference Guide , Vol. II gives the access rights required 
to use the AC$SET call. 



CHANGING ACCESS TO AN OBJECT 



Command Command Function Subroutine 



EDIT_AOCESS | None AC$CHG 

EDAC 



Changing Access to an Object (Command) : To change an existing ACL on a 
file system object from PRBDS command level, use the command: 

| EDIT_ACCESS ) objeotname user-id : access-rights ... 
I EDAC 
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The object name argument identifies a file system object that already 
has an ACL of any type: specific, category, or default. The object 
can be identified by any valid form of pathname. The ACL argument (s) 
identify one or more individ-ual entries on the list that are to be 
added, deleted, or changed. Only the specified entries are affected; 
unreferenced entries are left on the list unchanged. 



Changing Access to an Object (Command Function) : There are no command 
functions to modify access categories. A CPL program that needs to 
modify one can use the appropriate PRIMOS command as a program 
statement . 



Changing Access to an Object (Subroutiae) : To change an existing ACL 
on an object from a program, use the subroutine: 



AC$CHG (name, addr(acl_struc) , code) 



addr(acl_struc) 



arguments have the 
AC$SET call described 
changing access, and 



In the AC$CHG call, the name and 

same functions and requirements as in the 

earlier. This is the fundamental call used for 

behaves in the same way as the EDAC command. There are other methods, 

which are described in Chapter 7, ACCESS CONTROL LISTS (ACLS), used to 

change an existing ACL to that of another object and to make selective 

modifications to it afterwards. 



DELETING ACCESS CONTROL ENTRIES 


Command Command Function Subroutine 


( SET ACCESS 
i SAC 

j EDIT_ACCESS 
I EDAC 


None AC$SET 
None AC$CHG 



Deleting ACL Entries : There are no explicit commands, command 
functions, or subroutines that perform the sole function of deleting an 
ACL entry or entries; the basic approach to accomplish this is to use 
the SET_ACCESS or EDTT_ACCESS functions, and to include entries that 
contain the special access right NONE. 

For example, if an ACL contains an entry BAKER:LUR and you want to 
exclude user BAKER from any access at all, you can use the EDIT_ACCESS 
command (or the AC$CHG subroutine call), specifying the explicit entry 
BAKER: NONE. This explicitly states that user BAKER has access NONE, 
and an entry to this effect is placed on the ACL. Alternatively, you 
can use the EDIT_ACCESS command, specifying BAKER:, that is, the 
user-id and the colon, but no access rights. This results in the entry 
for user BAKER being deleted from the ACL entirely. 
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You can also use the SET_AOCESS command (or the AC$SET subroutine call) 
and explicitly specify all of the entries on the existing ACL except 
the entry for BAKER. 

Using the EDIT_AOCESS command is much the easier method, especially if 
the ACL is long and complex. 



CREATING FILE SYSTEM OBJECTS 

File system objects are created in several different ways, depending on 
the type of object. In order to create any type of object, you (at 
command level) or your program's user, must have Add access to the 
directory immediately containing the object, and Use access to any 
higher-level directories. 

For those objects that can be created at command level (file 
directories, files, and access categories), you can specify either a 
simple name to create the object in the home directory, or a pathname 
to create the object in any other directory for which you have the 
appropriate access. 

At subroutine level, you can use any of several subroutine calls to 
create an object, depending on its type and location. All types of 
objects can be created at this level. 



Creating File Directories 

In order to create a directory, you (or your program's user) must have 
Add access to the directory (which may be the MFD) that will contain 
the directory, and Use access to any directories that are superior to 
the one being created. 





CREATING FILE DIRECTORIES 


Command 


Command Function Subroutine 


CREATE 


None DIR$CR 

CREA$$ * 



* The CREA$$ subroutine is documented in Appendix A of 
the Subroutines Reference Guide , Vol. II. It is 
considered obsolete at ERIMOS Rev. 20.2. Although 
CREA$$ is still supported, programs should use DIR$CR 
beginning with Rev. 20.2. 
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Creating a File Directory (Command) : To create a file directory from 
command level, use the command: 

CREATE directory_pathname [-MAX n] [-CATEGORY acatname] 



The directory_pathname argument can be any legitimate form of pathname, 
implying that you can create a file directory anywhere, provided, of 
course, that you have the appropriate access. The ACL of the new 
directory will be the same as that of the containing directory; you 
can modify it once the directory exists by using any of the access 
control commands described previously. 

Creating a File Directory (Command Function) : You can include the 
CREATE command in a CFL program in the same form that you use when you 
enter the command at your terminal; if you invoke the CFL program from 
your terminal, the results are the same, including the return of error 
messages. However, if you invoke the CFL program as a phantom, no 
error messages are returned to your terminal. The program would not, 
for example, return a message if you were to try to create a directory 
that already existed. It would therefore be wise to check for the 
existence of the directory before attempting to create it; you can use 
the [EXISTS] command function for this purpose, as described in the CFL 
User's Guide. 



Creating a File Directory (Subroutine) : To create a file directory 
from a program, use the subroutine cal l : 

DIR$CR (dirname, addr(attributes) , code) 



The DIR$CR subroutine creates a lower-level directory in the location 
indicated by the pathname. It creates a password directory if the 
current directory is a password directory; in this case, the owner and 
nonowner passwords are applied to the new directory. If the current 
directory is an ACL directory, the new directory is also an ACL 
directory; in this case, any passwords supplied in the call are 
ignored. 



NOTE 

The CREFW$ subroutine creates a password directory within an 
ACL directory. It is documented in Appendix A of the 
Subroutines Reference Guide , Vol. II. CREFW$ is considered 
obsolete at FRBiOS Rev. 20.2. Although CREPW$ is still 
supported, programs should use DIR$CR beginning with Rev. 20.2. 
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Creating Files 

In order to create a file, you (or your program's user) must have Add 
access to the directory that is to contain the file, and Use access to 
all superior directories leading to this directory. 





CREATING FILES 




Command 


Command Function 


Subroutine 


None 


None 


SRCH$$ 
SRSFX$ 

TSRC$$ * 



* The TSRC$$ subroutine is documented in Appendix A of 
the Subroutines Reference Guide , Vol. II. It is 
considered obsolete at FRIMOS Rev. 20.2. Although 
TSRC$$ is still supported, programs should use SRSFX$ 
beginning with Rev. 20.2. 

Creating a File (Command) : There is no command that explicitly creates 
a file; files are implicitly created by FRIMOS programs such as ED, 
the compilers, the FMA assembler, and the linkers SEG, LOAD, and BIND. 

An empty file is implicitly created from FRIMOS command level if the 
OPEN command is given to open a nonexistent file for writing or for 
reading and writing. Opening file system objects is discussed in more 
detail later in this chapter and in Chapters 5, TEXT STORAGE AND 
RETRIEVAL and 6, DATA STORAGE AND RETRIEVAL. 



Creating a File (Command Function) : As at FRIMOS command level, there 
is no command function that explicitly creates a file; you can include 
the OPEN command as a CPL program statement if you want the program to 
create an empty file. 

Creating a File (Subroutine) : To create a file from a program, use one 
of the subroutine calls: 



SRCH$$ (key, name, name_len, unit, type, code) 

SRSFX$ (key, name, unit, type, num_suf fixes, suffixes, 
basename, suffixjused, code) 



These calls are described in greater detail in Chapter 5, TEXT STORAGE 
AND RETRIEVAL, and in Volume II of the Subroutines Reference Guide. 
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In all cases, the newfile portion of key specifies the type of file 
(SAM or DAM) to be created if the object specified by name does not 
exist and the action to be performed is writing or reading and writing. 

For the SRCH$$ call, the name argument is a simple name; the resulting 
file is created in the current directory and given the same protection 
as that of the current directory. 

For SRSFX$, name is any form of pathname; the resulting file is 
created in the directory specified by the directory portion of name, 
and given its protection. 

Creating Access Categories : The creation of access categories was 
described earlier in the section entitled Access Control Functions. 



OPENING FILE SYSTEM OBJECTS 

To open a file system object, you (or your program's user) must have 
Use access to all directory levels leading to the object to be opened. 
Additional rights required on the object itself and its containing 
directory depend on the action to be performed on the opened object. 

As described previously, attempting to open a nonexistent file normally 
results in that file being created in an empty state; the discussion 
in the following subsections assumes that the object already exists. 



Opening File Directories 

File directories can be opened at both command level and at subroutine 
level; however, they can be opened only for reading. File directories 
are written to implicitly whenever some action on or within the 
directory requires that information in the directory be updated (such 
as the date-time-last -modified or access control information). 





OPENING FILE DIRECTORIES 




Command 


Command Function 


Subroutine 


OPEN 


OPEN_FILE 


SRCH$$ 
SRSFX$ 
TSRC$$ * 



* The TSRC$$ subroutine is documented in Appendix A of 
the Subroutines Reference Guide , Vol. II. It is 
considered obsolete at PRIMOS Rev. 20.2. Although 
TSRC$$ is still supported, programs should use SRSFX$ 
beginning with Rev. 20.2. 
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Opening File Directories (Command) : There is not much to be gained 
from opening a file directory interactively, since there are no 
commands that enable you to read the directory interactively. However, 

PRIMOS will not prevent your doing this; if you want to open a file 
directory from PRIMOS command level, use the command: 



OPEN pathname funit key 

The pathname argument can be any form of pathname leading to a file 
directory to which you have Read access. You must specify a file unit 
number funit ; PRIMOS does not look for an unused file unit when an 
object is being opened from command level. The key^ argument must 
specify a value of 1 (read). See the PRIMPS Commands Reference Guide 
for a full description of the OPEN command. 

Opening File Directories (Command Function) : PRIMPS will allow a file 
directory to be opened by the OPENJFILE command function, but will not 
allow any other operations (other than CLOSE) to be performed on it. 
Use the following form in a CPL program: 

&set_var unit := [OPENJFILE pathname status -MODE R] 



In this CPL statement, unit is a local or global variable that receives 
the file unit number assigned to the opened directory by PRIMOS; 
status is a local or global variable that receives the status code 
resulting from the operation. The pathname argument can be any of the 
valid forms. See the PRIMOS Commands Reference Guide and the CPL 
User's Guide for more detailed descriptions of the OPENJFILE command 
function. 



Opening File Directories (Subroutine) : To open a file directory from a 
program, use calls to the subroutines described previously for creating 
file system objects: 

SRCH$$ (key, name, name_len, unit, type, code) 

SRSFX$ (key, name, unit, type, num_suf fixes, suffixes, basename, 
suffix_used, code) 

In all cases, the action portion of key specifies the action(s) to be 
performed (read, write, or read and write). 
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For the SRCH$$ call, the name argument can he only a simple name, the 
name of the directory being searched for in the current directory. 



For SRSFXS, name is any form of pathname. 



Opening Files 

Files contained in file and segment directories can be opened for 
reading, writing, or reading and writing at command, command function, 
and subroutine levels. In all cases, Use access is required on the 
containing directory and superior directories, and Read, Write, or Read 
and Write access is required on the file, depending on the actions to 
be performed. 





OPENING FILES 




Command 


Command Function 


Subroutine 


OPEN 


OPEOTLE 


SRCH$$ 
SRSFX$ 
TSRC$$ * 



* The TSRC$$ subroutine is documented in Appendix A of 
the Subroutines Reference Guide , Vol, II. It is 
considered obsolete at PRIMDS Rev. 20.2. Although 
TSRC$$ is still supported, programs should use SRSFX$ 
beginning with Rev. 20.2. 

Opening Files (Command) : To open a file (either text or data) from 
command level, use the command: 



OPEN pathname funit key 

The pathname argument can be any form of pathname leading to a file. 
You must specify a file unit number funit ; PRIMOS does not look for an 
unused file unit when opening a file from command level. The key 
argument must specify a value indicating the action to be performed. 
Refer to the PRIMOS Commands Reference Guide for details on the use of 
the OPEN command and its arguments. 

Opening Files (Command Function) : To open a file (either text or data) 
from a CPL program, use a statement of the form: 

&set_var unit := [OPEN_JTLE pathname status -MODE x] 
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In this CPL statement, unit is a local or global variable that receives 
the file unit number assigned to the opened file by PRIMOS; status is 
a local or global variable that reoeives the operation's status code. 
The pathname argument can be any of the valid forms. The mode argument 
x specifies the action(s) for which the file is being opened: R 
TRead) , W (Write) , or RW or WR (Read and Write) . Note that if the file 
is being opened in any mode that allows writing and the file does not 
exist in the directory indicated by pathname , the file will be created 
with no indication of an error. Therefore, if proper operation of your 
CPL program depends on a pre-existing file of the specified name, it 
would be wise to test for its existence before opening it for writing. 
See the PRIMOS Commands Reference Guide and the CPL User's Guide for 
more detailed descriptions of the OPEN_FILE command function. 

Opening Files (Subroutine) : To open a file from a program, use calls 
to the subroutines described previously for creating and opening file 
system objects: 

SRCH$$ (key, name, name_len, unit, type, code) 

SRSFX$ (key, name, unit, type, num_suf fixes , suffixes, basename, 
suffix_used, code) 



In all cases, the action portion of kejr specifies the action(s) to be 
performed (read, write, or read and write). 

For the SRCH$$ call, the name argument can be only a simple name, the 
name of the file being searched for in the current directory. 

For SRSFX$, name is any form of pathname. 

Segmented files (members of a segment directory) can be open ed by the 
SGD$OP subroutine call, described in Chapters 5, TEXT STORAGE AND 
RETRIEVAL and 6, DATA STORAGE AND RETRIEVAL. 



READING FILE SYSTEM OBJECTS 

After an object has been opened, it can be read under certain 
conditions and from some, but not all, programmer interface levels. 
From the command level, directories cannot be read, nor can 
fixed-length data records; variable-length text records can be read 
and displayed on the terminal, but only indirectly through a command 
function. Any kind of object can be read from program level by use of 
several special-purpose subroutines, as well as some of the 
general-purpose subroutines already described. In all cases, Read 
access is required on the object to be read, and Use access is required 
to all superior directories. 
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READING DIRECTORIES 




Command 


Command Function 


Subroutine 


None 


None 


DIR$LS 
DIR$SE 
DIR$RD 
ENT$RD 
SGDR$$ 



Reading Directories (Command and Command Function) : There is no 
mechanism by which directory entries can be read from command level or 
from command function level. This applies to both file and segment 
directories. (Directory contents can, of course, be displayed or 
written to a CCMO file by using the LD command. ) 

Reading Directories (Subroutine) : Your program can read file 
directories in several ways using any of the following subroutine 
calls: 



DIR$LS (dir-unit, dir-type, initialize, desired-types, 
wild-ptr, wild-count, return-ptr, max-entries, 
entry-size, ent-returned, type-counts, 
bef ore-date, after-date, code) 



DIR$SE (dir-unit, dir-type, initialize, sel-ptr, 
return-ptr, max-entries, entry-size, 
ent-returned, type-counts, max-type, code) 



DIR$RD (key, unit, return-ptr, max-return-len, code) 



ENT$RD (unit, name, return-ptr, max-return-len, code) 



DIR$LS is a general-purpose directory searcher that takes arguments 
used to select entries to be searched for. Selection criteria can be 
object types, wild-card names, date and time last modified, or 
combinations of these. Selection can not be by date and time last 
acoessed or date and time created. Either file or segment directories 
can be read. Selection can begin at the beginning of the directory or 
at the current position; entries are returned in a structure provided 
by the program that is capable of holding max-entries entries, and are 
pointed to by return-ptr . This call is fully described in Volume II of 
the Subroutines Reference Guide . 

DIR$SE extends the functi onalit y of DD3$LS by using a structure to 
> contain additional selection criteria, including date and time last 
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aooessed aM date aM time created. DIR$SE is fully described in 
Volume II of the Subroutines Reference Guide . 

DIR$RD reads the contents of a directory sequentially, one entry at a 
time, and returns each entry read in a program-provided structure 
pointed to by return-ptr . It returns only named file system objects, 
and therefore cannot be used to read subentries in a segment directory. 
It returns names for files, file directories, and access categories. 
This call is described more fully in Chapter 6, DATA STORAGE AND 
RETRIEVAL, and in Volume II of the Subroutines Reference Guide . 

ENT$RD is used to read the contents of a specific directory entry whose 
name is given as the name argument. The entry is returned in a 
structure identical to that used by DIR$RD, and pointed to by 
return-ptr . The entry being searched for must exist in the current 
directory, since name is defined as having a length of 32 characters. 
This call is described in detail in Volume II of the Subroutines 
Reference Guide . 

Segment directories can be read by using either of the following calls: 

DIR$LS (dir-unit, dir-type, initialize, desired-types, 
wild-ptr, wild-count, return-ptr, max-entries, 
entry-size, ent-returned, type-counts, 
bef ore-date, after-date, code) 

SGDR$$ (key, unit, starpositn, end_position, code) 

DIR$LS is used as described for file directories, except that dir-type 
must have a value of 2 for a SAM segment directory, or 3 for a DAM 
segment directory. 

SGDR$$ returns an integer representing the position in the directory of 
the first or next full or free position in the segment directory, 
depending on the values of key and start_position . The key argument is 
K$FULL or K$FREE to look for full or free entries, respectively. A 
start_position value of zero (0) looks for the first entry; a value 
equal to the position of the last full or free entry plus 1 looks for 
the next entry. The position integer is returned in end_position . The 
SGDR$$ call is described in detail in Chapter 6, DATA STORAGE AND 
RETRIEVAL, and in the Subroutines Reference Guide, Volume II. 





READING FILES 




Command 


Command Function 


Subroutine 


None 


READ_FILE 


RDLTNS 
FRWF$$ 
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Reading Files (Command) : There axe no commands that enable you to read 
a file directly from PRIMOS command level. However, a text file can be 
read indirectly and displayed to your terminal (or written to a OOMO 
file), one line at a time, by using a TYPE command whose argument is a 
[READJFILE] command function, described next. 



Reading Files (Command Function) : You can read an ASCII (text) file 
from a CPL program by including a statement of the form: 

&set_var read_data := [READ_FILE unit status_var] 

In this CPL statement, unit is the decimal number of the file unit on 
which the file has been previously opened. You supply local or global 
variable names for the variables read_data and status_var . The former 
receives the line of text read from the file, while the latter stores 
the return code from the execution of the read. (The setting and 
evaluating of variables, and the use of the READ_FILE command function, 
are described in the CPL User's Guide ). 

Reading Files (Subroutine) : To read a file from a program, use one of 
the following subroutine calls: 

RELETS (unit, inputJLine, max_line_length , code) 

PRWF$$ (key, unit, addr (buffer ) , size, pre_posn, 
halfwords_read, code) 



The RDLINS call is used to read variable-sized records from a file open 
on unit into a buffer, pointed to by input_J1ne . Reading <=*n dg when a 
new-line character is encountered. If the number of characters read is 
less than max_line_length , the remaining buffer characters are 
blank-filled. The RnTiTTCS calling sequence is illustrated in Chapter 5, 
TEXT STORAGE AND RETRIEVAL; the subroutine's operation is further 
explained in Chapter 5, TEXT STORAGE AND RETRIEVAL, and in the 
Subroutines Reference Guide , Vol. II. 

Use the PRWF$$ call to position and read fixed-length data files. 
Positioning and reading are only two of many functions that PRWF$$ can 
perform; its complete functionality is described in Chapter 5, TEXT 
STORAGE AND RETRIEVAL, and in the Subroutines Reference Guide , Vol. II. 

In addition to RDLINS and PRWF$$, there are subroutines whose functions 
are to read from other than disk devices: RDASC reads ASCII characters 
from any device, while RDBIN reads binary data from any device. These 
subroutines are described in the Subroutines Reference Guide, Vol. II. 
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WRITING FILE SYSTEM OBJECTS 





WRITING DIRECTORIES 




Command 


Command Function 


Subroutine 


None 


None 


SGDR$$ 
SGDSDL 



File and segment directory objects are most often written to 
implicitly, as a result of performing some function on a subordinate 
object that reflects a need to add or update control information in its 
containing directory. Each time a file open for writing is closed, for 
example, the date-time-last-modified information in the containing 
directory needs to be changed; this is done as an implicit byproduct 
of the close operation. No writing to directories of either type can 
be done explicitly by commands or command functions, and only a limited 
number of writing operations can be done to directories at subroutine 
level, and these only on segment directories. Likewise, there are no 
commands by which you can explicitly write records to a file from 
command level; you can, however, write variable-length text records 
using a command function in a CFL program. 

Write access is required on any object to be written to; Use acoess is 
required to all superior directories, and Add acoess is required to the 
cont aining directory if a previously nonexistent file is being written 
into that directory. (If the name of a file or other object in a 
directory is being changed, Delete as well as Add acoess is required on 
the containing directory.) 

Writing Segment Directories (Subroutine) : You can effectively write to 
a segment directory from program level by using the subroutine calls: 

SGDR$$ (key, unit, new_size, ignored, code) 
SGD$DL (unit, code) 



The SGDR$$ call is used to extend or truncate a segment directory open 
on unit by specifying the key^ value K$MSIZ and the new number of 
members in the newjslze argument. The ignored argument is not used, 
and should be zero (0). 

The SGD$DL na il is used to delete a member of the segment directory 
open on unit . If the member deleted is not the last member of the 
directory, effectively the size of the directory does not change; it 
will change only if the member deleted is the last one. 

Both of these subroutines and their calling sequences are described in 
Chapter 6, DATA STORAGE AND RETRIEVAL. 
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WRITING FILES 




Ctammand 


Command Function 


Subroutine 


None 


WRITEJFILE 


WTLIN$ 
PRWF$$ 



Writing Files (Command) : There is no direct command by which a text 
line or data file record can be written from command level. You can, 
however, write a text line using the WRITE_FILE command function 
described next. 



Writing Files (Command Function) : You can write text files (but not 
data files) from a CEL program by using the command function: 



[WRITE_FILE unit text] 



The unit argument is the file unit number of a text file previously 
opened for writing or for reading and writing. The text to be written, 
represented by text , can be either literal text (enclosed in quotes if 
it contains spaces or special characters), or the current contents of a 
local or global variable previously set by a command function such as 
RESPONSE. Refer to the CPL User's Guide for further information on the 
WRITE_FILE command function. 



Writing Files (Subroutine) : To write a file from a program, use one of 
the following subroutine calls: 

WTLIN$ (unit, outputjline, max_line_length, code) 

PRWF$$ (key, unit, addr(buf fer) , size, reLposn, 
lhalfwords_read, code) 



The WTLIN$ call is used to write variable-sized (usually ASCII text) 
records to a file open on unit from a buffer, pointed to by 
output_line . Writing ends when a new-line character is encountered. 
If the number of characters written is less than max_i i ™*_length , the 
remaining characters in the buffer are blank-filled. The WTLIN$ 
calling sequence is illustrated in Chapter 5, TEXT STORAGE AND 
RETRIEVAL^ the subroutine's operation is further explained in Chapter 
5, TEXT STORAGE AND RETRIEVAL, and in the Subroutines Reference Guide , 
Vol. II. 

Use the PRWF$$ call to position and write fixed-length data files. 
Positioning and writing are only two of many functions that PRWF$$ can 
perform; its complete- functionality is described in Chapter 5, TEXT 
STORAGE AND RETRIEVAL, and in the Subroutines Reference Guide, Vol. II. 
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In addition to WTLIN$ and PRWF$$, there are subroutines whose functions 
are to write to other than disk devices: WRASC writes ASCII characters 
to any device, while WRBIN writes binary data to any device. These 
subroutines are described in the Subroutines Reference Guide, Vol. IV. 



CLOSING FILE SYSTEM OBJECTS 

Any file system object that is capable of being opened from command, 
command function, or subroutine level is also capable of being closed. 
Objects can be closed only by the CLOSE command or a subroutine; there 
is no CLOSE_FILE command function to match the OPENJFILE command 
function. However, the CLOSE command can be included in a CPL program 
either with or without the enclosing brackets ([ ]); the results are 
identical. 



CLOSING FILE SYSTEM OBJECTS 



Command 


Command Function 


Subroutine 


CLOSE 


CLOSE 


CLOSFU 
CLOSFN 
SRCH$$ 
SRSFX$ 
TSRC$$ * 



* The TSRC$$ subroutine is documented in Appendix A of 
the Subroutines Reference Guide , Vol. II. It is 
considered obsolete at PRIMOS Rev. 20.2. Although 
TSRC$$ is still supported, programs should use SRSFX$ 
beginning with Rev. 20.2. 



Closing Objects ((Command and Command Function) : To close an object 
from command or command function level, use one of the following: 



CLOSE objectname 
[CLOSE objectname] 



The objectname argument is any valid, form of pathname. The CLOSE 
function does not return a code indicating that an object is not open; 
it does, however, return a code if the object is not found. 
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dosing Objects (Subroutine) : To close a file system object from 
program level, use one of the subroutine calls: 

CLO$FU (unit, code) 

CLO$FN (pathname, code) 

SRGH$$ (key, objectname, name_length, unit, type, code) 

SRSFX$ (key, pathname, unit, type, n-suf fixes, suffix-list, 
basename, suffix-used, code) 



CLO$FU and CLO$FN are simplified interfaces to close file system 
objects by file unit number and pathname, respectively. Their calling 
sequences and operations are described more fully in Chapter 5, TEXT 
STORAGE AND RETRIEVAL. 

SRCH$$ and SRSFX$ both require a kegr value of K$CLOS to close an 
object. SRCH$$ accepts only a simple object name, and closes the named 
object in the current directory. SRSFX$ can close an object anywhere 
in the file system (assuming appropriate access, of course). These 
subroutines are fully described in Volume II of the Subroutines 
Reference Guide. 



See also the description of the CLOS$A subroutine, part of the 
Application Library package, given in Volume IV of the Subroutl ves 
Reference Guide. 



DELETING FILE SYSTEM OBJECTS 

Any file system object that has been created, by whatever means, can 
also be deleted. Not all types of objects, however, can be deleted 
from all interface levels: you cannot, for example, delete an 
individual segment from a segment directory from command or command 
function level. 

Delete access is required for the directory containing the object to be 
deleted; Use access is required for all superior directory levels. 
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DELETING FILE SYSTEM OBJECTS 



Command 


Command Function 


Subroutine 


DELETE 


None 


SGD$DL 
SRCH$$ 
SRSFX$ 

fil$dl 

TSRC$$ * 



* The TSRC$$ subroutine is documented in Appendix A of 
the Subroutines Reference Guide , Vol. II. It is 
considered obsolete at PRIMOS Rev. 20.2. Although 
TSRC$$ is still supported, programs should use SRSFX$ 
beginning with Rev. 20.2. 

Deleting Objects (Command) : To delete a file, file directory, segment 
directory, or access category from command level, use the command: 



DELETE objectname [options] 



Objectname is any valid form of pathname in which you have the 
appropriate acoess rights; you can therefore delete an object anywhere 
in the file system. The values that you can supply for the options 
argument are described in the PRIMOS Commands Reference Guide . 

Note that there is no abbreviated form of the DELETE command. 

Deleting Objects (Command Function) : There is no command function to 
delete a file system object. However, the DELETE command can be 
included in a CPL program. 

Deleting Objects (Subroutine) : To delete a file system object from a 
program, use one of the following subroutine calls: 



SGD$DL (unit, code) 

SRGH$$ (key, objectname, nam_length, unit, type, code) 

SRSFX$ (key, pathname, unit, type, n-suf fixes, suffix-list, 
basename, suffix-used, code) 

FIL$DL (pathname, code) 
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The SGD$DL call is used only to delete members of a segment directory. 
The program must first position to the desired segment number. See How 
to Position a Segment Directory in Chapter 6, DATA STORAGE AND 
RETRIEVAL. The unit argument gives the file unit number on which the 
segment directory was previously opened. 

For SRCH$$ and SRSFX$, the value of kej is K$DELE to delete an object. 
For SRCH$$, objectname is the simple name of an object in the current 
directory; if the object is a directory, the deletion will occur only 
if the directory is empty. 

SRSFX$ can delete objects anywhere in the file system, provided the 
program's user has Delete access to the containing directory, and the 
objects are not delete-protected. 

These calls are described further in Chapters 5, TEXT STORAGE AND 
RETRIEVAL and 6, DATA STORAGE AND RETRIEVAL, and in Volume II of the 
Subroutines Reference Guide . See also the description of the DELE$A 
subroutine, part of the Application Library package, given in Volume IV 
of the Subroutines Reference Guide. 
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Search Rules 



This chapter describes the search rules facility provided with Rev. 
21.0 of PRIMOS. It provides a conceptual overview of the search rules 
facility and describes how you can both modify system-supplied lists of 
search rules and create your own search lists. The search rules 
facility permits you to invoke a runtime search operation to locate an 
object, rather than specifying the exact location of the object. It is 
an important programming tool to enhance the generality, flexibility, 
and performance of many types of operations. 



SEARCH RULES AND SEARCH LISTS 

The PRIMOS search rules facility is a general-purpose mechanism for 
specifying a search sequence. It enables you to prespecify locations 
for PRIMOS to use when conducting a search. Each prespecified location 
is known as a search rule . A search rule names a location that may 
contain the object of the search. For example, a directory name would 
be a search rule when the object of the search is a file. 

Search rules are grouped into sequences known as search lists . A 
search list is an area in memory that contains search rules, listed in 
sequential order. You initially write the sequence of search rules 
into a text file known as a search rules file . Before these search 
rules can be used, they must be copied from the search rules file into 
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a search, list. The process of copying search rules into a search list 
is known as setting the search, list. 

When using a search list , PRIMOS searches the first search rule in the 
search, list, then the second search, rule in the list, and so forth 
until PRIMOS either finds the object of the search or encounters the 
end of the search list. 

One common use of search rules is to locate file system objects without 
requiring the user to enter the fully qualified pathname. You can 
create different search lists for different kinds of search operations. 
For example, you can establish a search list to search multiple disk 
partitions for a top-level directory or establish a search list to 
search multiple directories for a file. 

You can invoke such a search by using a PRIMOS command, a CPL function, 
or a subroutine call. The EXPAND_SEARCH_RULES command, for example, 
takes a filename as input and uses the search rules facility to 
determine the absolute pathname of that file. The search rules 
facility is invoked automatically by system software, such as the 
PRIMOS command processor and the BIND program linker. 

PRIMOS maintains a separate group of search lists for each process. 
This means that users can customize their search lists to meet 
individual requirements. Because a group of search lists is specific 
to a process, a program uses the search lists of the user (or phantom) 
currently executing the program. To avoid possible mismatches between 
programs and search lists, you can include in the program calls to 
search rule subroutines that check or set your search lists. You 
cannot use, read, or set search lists that belong to other users' 
processes. The use of search lists is not affected by the user's 
current command level or attach point. 



Default Search Lists 

PRIMOS provides system default rules for five special-purpose search 
lists. These five search lists are included in the search lists of 
every user on the system. These search lists and their default rules 
are automatically set when a user logs in or otherwise initializes a 
process. The five special-purpose search lists are the following: 

ATTACKS searches partitions to locate top-level directories. 
COMMANDS searches directories to locate executable code files. 
INCLUDES searches directories to locate source code files. 
BINARYS searches directories to locate bi n ary object code files. 
ENTRYS searches EPF library files to locate entrypoints. 
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In addition to these five special-purpose search lists, you can set 
other, general-purpose search lists for the duration of a process. 
These search lists are referred to as user-defined search lists . 
During a process you can add, delete, or modify the search rules in any 
of your search lists. Search rules that you add. to a search list (of 
any type) are referred to as user-specified search rules . 



ADVANTAGES OF SEARCH RULES 

The use of search rules provides several benefits: 

• Search rules enable users to locate items at runtime without 
knowing their exact location. You specify this location 
information when you create the search list. When the search 
list is used, PRIMOS searches these listed locations for the 
object of the search. Once these search lists have been set, 
you do not have to specify (or even know) the full pathname in 
order to retrieve each item. Naive users can be supplied with 
search lists that make knowledge of the file system architecture 
unnecessary. 

• PRIMOS searches the rules in a search list in the listed order. 
By rearranging the search rules in a list, you can improve 
performance in searching for an item. This is particularly 
significant when searching multiple disk partitions for a 
directory. 

• PRIMOS stops searching when it finds a match. Because a search 
operation uses the search rules to find the first occurrence of 
an item, you can maintain multiple items with identical 
filenames on the system and sequence the search rules to find 
the desired instance of that item. For example, if you have 
several revisions of the same file in different directories, you 
could list your search rules so that they always locate the 
directory cont aining the most recent version of the file. When 
you create a new version of the file, you simply add the name of 
that version's directory to the top of the search list. 

• PRIMOS searches only those items that are specified in the 
search list. By changing the contents of a search list, you can 
restrict the scope of a search to only those locations where the 
desired item is likely to be found. For example, if a program 
always accesses a directory located on one of a small group of 
disk partitions, you would create a search list to search only 
those partitions, thus avoiding a search of all partitions on 
the system and preventing access to inappropriate directories. 
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The use of search rules can greatly simplify program and terminal 
operations, can increase the flexibility of programs and thus reduce 
maintenance overhead, and can improve the performance of search 
operations. However, note that failing to set a search list or 
modifying the rules in a search list can result in unexpected changes 
to the execution of programs. 



SEARCH RULE TYPES 

A search list can consist of three types of search rules: 
administrator rules, system rules, and user-specified rules. 



Administrator and System Search Rules 

PRIMOS sets a group of search lists when you log in or otherwise 
initialize a process. These search lists are initialized with 
administrator search rules and system search rules. In each search 
list, administrator rules appear first, followed by system rules. 
PRIMOS assigns the same administrator and system rules to every process 
on the system. 

Administrator search rules permit the System Administrator to regulate 
the use of search rules throughout the system. System search rules 
provide all users on the system with the same default search 
environment for normal PRIMOS operations. The search lists that PRIMOS 
sets when you initialize a process can contain just administrator 
rules, just system rules, or both administrator and system rules. 

When you set a search list to user-specified rules, PRIMOS 
automati ca lly prefaces your user-specified search rules with 
administrator and system rules. You can override the placement of 
system rules in a search list. You cannot override the placement of 
administrator rules in a search list. 

Administrator snH system search rules are located in search rules files 
found in directory <0>SEARCH_RULES* on the command device. This 
directory provides search rules for ATTACKS, COMMANDS, ENTRYS, BINARYS, 
and INCLUDES. The System Administrator can modify these search rules 
files and can add administrator or system search rules files to this 
directory for other search lists. If either an administrator or system 
search rules file exists in SEARCH_RULES* , PRIMOS automatically sets a 
corresponding search list whenever a process is initialized. Refer to 
the System Administrator's Guide, Volume III for further details on 
administrator and system search rules. 
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User-speolf ied Rules 

You can specify new search rules to add to existing search lists. You 
can also specify search rules for new, user-defined search lists. 

When adding rules to an existing search list, you can specify whether 
you wish the system rules to preface your user-specified rules (the 
default), to be excluded from the search list, or to be placed in a 
designated location in the search list. If administrator rules have 
been established for a search list, they always precede the 
user-specified rules and system rules. User-defined search lists have 
no corresponding administrator or system search rules. 



SEARCH LIST TOPES 

FRIMOS permits you to create your own search lists. It also provides 
support for five special-purpose search lists: ATTACKS, COMMANDS, 
ENTRY$, BINARYS, and INCLUDES. 



User-defined Lists 

You can use a user-defined search list to search directories for file 
system objects (files, subdirectories , segment directories, and access 
categories). You create a search list that consists of the pathnames 
of the directories that you wish to search for these file system 
objects. Each directory pathname is a separate search rule. The 
following are typical search rules for a user-defined search list. 



glean 

glenn>project 
alan>project 
glenn>pro ject >tests 
glenn>status 



How to create and name a user-defined search list is described later in 
this chapter, in the section named Creating and Setting Search Rules . 

You can use the EXPAND_J£EARCH_RULES (ESR) command or a subroutine call 
to search a user-defined search list. You specify the full name (name 
and suffix) of the file system object that is the object of the search, 
and the name of the search list. The ESR command returns the object's 
absolute pathname. The OPSR$ and OPSRS$ subroutines locate and open 
the file. 

You can use the SR$SETL subroutine to define the locator pointer values 
for rules in user-defined search lists. This advanced operation 
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permits you to freely define the objects of a search. For further 
details, refer to the SR$SETL subroutine in the Subroutines Reference 
Guide, Volume II . 

You must set user-defined search lists during the process in which they 
are used. User-defined search lists are automatically deleted at the 
conclusion of the process. 



ATTACKS 

You use the ATTACKS search list to search disk, partitions for top-level 
directories. The ATTACKS search list, should contain the names of these 
partitions in the desired search sequence. The following are typical 
search rules for an ATTACKS search list: 



<sysdisk> 
<workdisk> 
<backupdisk> 
-added disks 



To use this search list, you specify the name of a top-level directory 
as the object of the search. PRIMOS searches each of the partitions in 
the sequence you specified. PRIMOS stops searching when it finds the 
first top-level directory with the name you requested. 

The default for the ATTACKS search list is a single search rule: the 
-added_disks keyword. This keyword causes PRIMOS to search the 
complete list of added disks in the following sequence: local disk 
partitions in the order added, then remote disk partitions in the order 
added. If your system has few added remote disk partitions, it is 
recommended that you end your ATTACKS search list with the -added_disks 
keyword. If your system has many added remote disk partitions, it is 
recommended that you specify by name all local disk partitions and 
needed remote disk partitions in the ATTACKS search list; do not 
include the -added_disks keyword in ATTACKS for such a system. 

The ATTACH command uses the ATTACKS search list. If an ATTACH request 
specifies a pathname that does not include a partition name, the ATTACH 
command searches multiple partitions for the top-level directory of the 
pathname. If an ATTACKS search list is set, the ATTACH command uses 
the ATTACKS search list sequence to locate this top-level directory. 

The EXPAND_SEARCH_RULES (ESR) command uses the ATTACKS search list. 
You supply ESR with the name of a top-level directory, and it returns 
the absolute pathname of that directory (for example, <sysdisk>mydir) . 
If you supply an objectname (other than the name of an executable file) 
to the ESR command, and do not supply a search list name, ESR assumes 
the name refers to a top-level directory and automatically uses the 
ATTACKS list. 
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If no ATTACKS search list is set, PRIMOS defaults to a sequential 
search of all added disks. It first searches all local disk partitions 
in the order added, then all remote disk partitions in the order added. 

The ATTACKS search list can be invoked automatically by other search 
lists. This use of ATTACKS is described in the section ATTACKS Invoked 
by Other Search Lists . 



COMMANDS 

You use the COMMANDS search list to search directories for command 
files. A command file is any executable code file, such as a runfile 
or CPL file. A COMMANDS search list should contain the pathnames of 
the directories that you wish to search for executable code files. The 
following are typical search rules for a COMMANDS search list: 



cmdncO 

glenn 

glenn>project 

alan>project 

glenn>pro ject >tests 

glenn>status 



The default for COMMANDS is the directory CMDNCO, which contains the 
executable code files for PRBDS commands. This default permits you to 
execute FRIMOS commands without supplying complete pathnames. 

Once you have created a COMMANDS search list, you can execute a command 
file by simply typing its name, as if it were a PRIMOS command. For 
example, if you include the search rule mydir>subdir in your COMMANDS 
search list, you can execute the file mydir>subdir>mycfile.run from any 
attach point by simply typing mycfile. You do not have to specify the 
RESUME command or the filename suffix. PRIMOS searches each listed 
directory in sequence. PRIMOS stops searching when it finds the first 
file with the name you requested and (in order of preference) the 
suffix .RUN, .SAVE, .CPL, or a static-mode runfile with no suffix. 

You can also use the EXPAND_SEARCH_RULES (ESR) command to search the 
COMMANDS search list. If you instruct ESR to use the COMMANDS search 
list, you do not have to specify the .RUN, .SAVE, or .CPL filename 
suffix. If you instruct ESR to find a filename with a .RUN, .SAVE, or 
.CPL suffix, you do not have to specify use of the COMMANDS search 
list. ESR returns the absolute pathname of the command file, including 
its suffix. 
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INCLUDES 

Some language compilers use the INCLUDES search list to search, 
directories for source code files that are to be included during 
program compilation. An INCLUDES search list should contain the 
pathnames of the directories that you wish to search for source code 
files. The following are typical search rules for the INCLUDES search 
list: 



glenn 

glenn>tools 
glenn>pro ject >tests 
alan>subsystem>tests 

The compiler uses this search list when you specify the name of an 
include file during program compilation. You do not have to specify 
the filename suffix. 

The following compilers support INCLUDES: F77, C, Pascal, CBL, VRPG, 
and PL/I. If no INCLUDES search list is set, or a compiler does not 
support INCLUDES, the compiler assumes the include file is a source 
code file in the current directory. Refer to the i n di v idual language 
manuals for further details. 



BINARYS 

The BIND linker uses the BINARYS search list to search directories for 
binary (.BIN) files. A BINARYS search list should contain the 
pathnames of the directories that you wish to search for binary files. 
The following are typical search rules for a BINARYS search list: 



glenn 

glenn >compiles 

glenn>project >compiles 

alan>subsystem>compiles 

When running BIND, you specify the filename of the BIND load file, and 
ERIMOS searches the directories listed in BINARYS for that file. You 
do not have to specify the .BIN filename suffix. 

If no BINARYS search list is set, BIND assumes the load file is a 
binary file in the current directory. 
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ENTRY$ 

You use the ENTRY$ search list to search executable program format 
(EPF) or static-mode libraries for entrypoints. Each of these 
libraries can contain one or more entrypoints. The ENTRY$ search list 
should contain the pathnames of the library files that you wish to 
search for entrypoints. The following are typical search rules for an 
ENTRY$ search list. 



-primos_direct_entries 
LIBRARIES * >SYSTEM_LIBRARY . RUN 
LIBRARIES* >TTYCK$ . RUN 
LIBRARIES* >P0RTRAN_IO_LIBRARY . RUN 
LIBRARIES * >PASCAL_LIBRARY . RUN 
GLENN>PRIV LIB. RUN 



The ENTRY$ search list is used automatically when you execute a program 
that contains a dynamic link to an entrypoint. This dynamic link is 
established using BIND. During the BIND operation, you use the -dynt 
option to specify the name of the entrypoint. Then, during program 
execution, PRIMOS searches the libraries listed in ENTRY$ for the named 
entrypoint. For further details on this use of ENTRY$, refer to the 
Programmer's Guide to BIND and EPFs . 



CREATING AND SETTING SEARCH RULES 

Establishing user-specified search rules is a two-step process. First, 
you create a search rules file. A search rules file is a standard text 
file in which you write one or more search rules. After you create a 
search rules file, you use that file to set a search list. This set 
operation copies the rules in the search rules file into an area in 
memory established for the search list. All search operations are 
performed against the search list, not against the search rules file. 



Creating a Search Rules File 

You create a search rules file as a standard text file using EMACS or 
EDITOR. The naming conventions for search rules files are as follows: 

• Use the name format: xxx.listname.SR. In this format, xxx can 
be any name, listname is the name of the search list, and .SR is 
a suffix indicating a search rules file. 

• Do not use dollar signs ($) in the listname of user-defined 
search rules files. Dollar signs axe reserved for the listnames 
of special-pttrpose search rules files. 
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For example, you would use a search rules file with the name 

mylist . commands . sr 

to set the special-purpose search list COMMANDS. You would use a 
search rules file with the name 

yourlist . lookup . sr 

to set the search list LOCKUP. 

You can create multiple search rules files that can be used to set the 
same search list. Only one file at a time can be used to set a 
particular list. (This file can, however, contain keywords that draw 
upon the contents of other search rules files.) 

To plaoe rules in a search rules file, use EMACS or EDITOR to specify 
one search rule per line in the sequence that the items should be 
searched. A search rule can be up to 128 characters in length. A 
search rule can include the disk partition name, or it can begin with 
the top-level directory. If the disk partition name is omitted, the 
search rules facility uses the ATTACH$ search list to locate the 
appropriate partition. This use of ATTACKS is described later in the 
section ATTACKS Invoked by Other Search Lists . 

You can include comments, blank lines, and leading and trailing blanks 
in a search rules file. A comment begins with /* and continues to the 
end of the line. Comments and blanks in the search rules file are not 
copied into the search list during a set operation. 

When creating a search rules file, you should avoid duplicating 
administrator rules or system rules in your file. The one exception to 
this is if you plan to override the automatic inclusion of system rules 
when you set the search list. 

Setting Search Lists 

A search rules file is used to set a search list. Search lists are set 
when: 

• You initialize a process 

• You invoke a set operation 
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In both cases, the set operation copies search rules from one or more 
search rules files into an area in memory allocated for the search 
list. Because the set operation is a copy operation, the subsequent 
deletion or modification of the search rules file does not affect the 
search list. 

When a process is initialized, PRIMOS automatically performs set 
operations that copy the search rules from the search rules files in 
the directory <0>SEARCH_RULES* into search lists in memory. This 
creates a group of default search lists for that process. PRIMOS sets 
each search list with search rules copied from the administrator search 
rules file and the system search rules file for that list. If one of 
these search rules files does not exist, PRIMOS sets the search list 
with the contents of whichever of these search rules files does exist. 
If a list has neither type of search rules file, no search list is set 
during process initialization. 

You can set a search list by using the SET_SEARGHL_RULES (SSR) command 
or the SR$SSR subroutine. You supply the pathname of your search rules 
file to these set operations. You can also specify a name for the 
search list, or have the set operation derive the search list name from 
the name of the search rules file. 

If the search list did. not previously exist, the set operation creates 
that search list. If the search list did exist previously, the set 
operation either overwrites the old search rules or appends the new 
search rules to the search list. The set operation copies the rules in 
your search rules file into the search list. It may also copy 
administrator and system rules into the search list, if the appropriate 
search rules files are present in <0>SEARCH_RULES*. 

A set operation does not check your search rules against the contents 
of the file system. Therefore, you can set search rules that refer to 
partitions, directories, and so on, that do not yet exist in your file 
System. When a search operation is performed, PRIMOS uses each rule in 
a search list independently. An invalid reference in one search rule 
does not affect other search rules or halt the search operation. If a 
search rule names a nonexistent object, PRIMOS proceeds to the next 
rule in the search list. 

The SSR command returns a message if your search list has been set with 
duplicate rules. The SSR command sets the search list regardless of 
the presence of duplicate rules. A duplicate search rule in a search 
list can result in redundant searches but does not otherwise affect the 
search operation. 

The SSR command has an option that permits you to reset a search list 
to system defaults. You can also use the SR$INIT subroutine to reset 
search lists to system defaults. Other search rule subroutines are 
available to add or delete individual search lists and search rules. 
These subroutines act directly upon the search lists in memory and do 
not affect the corresponding search rules files. 
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Onoe you have set a search list, you can use the USTJ3EARCH_RULES 
(LSR) command, to display the search list. You can also use the SR$READ 
and SR$NEXTR subroutines to read the rules set In a search list. The 
SSR and LSR commands are further described in the PRIMPS Commands 
Reference Guide . Search rule subroutines are further described in the 
Subroutines Reference Guide, Volume II. 



SEARCH RULE KEYWORDS 

A search rules file can contain keywords that perform specific 
operations. Keywords that begin with a hyphen are directions to the 
search rules facility. These directions are carried out either when 
you set the search list or when you perform a search operation on that 
search list. Keywords enclosed in square brackets are variables for 
which the appropriate literal is supplied when the search list is used. 
The following are the available search rule keywords: 



-insert 

-system 

-optional 

-added_disks 

-static_mode_J 1 hraries 

-prijnos_direct_entries 

[origin_dir] 

[home_dir] 

[ ref erencing_dir ] 



You should place each keyword on its own line in a search rules file. 
Keywords and search rules can be intermixed in any sequence within a 
search rules file. Keywords can be written in either uppercase or 
lowercase. 



-insert 

The -insert keyword specifies the pathname of another search rules 
file. When you set the search list, ERIMOS inserts the contents of 
that search rules file at the point indicated by the -insert keyword. 
By using this keyword, you can set a large search list using several 
small search rules files. Search rules files can be nested. The 
SET_SEARCH_RULES command rejects circular references, such as a search 
rules file that includes itself. 

Figure 3-1 is an example of the -insert keyword. In this example, 
nested -insert keywords cause the contents of three search rules files 
to be included in the MYLIST search list. 
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SEARCH RULES FILES 
glenn > main.mylist.sr 




— ■► glenn >current.worklist.sr 



glenn >projl > routines 
glenn>proj1 >tools 
- insert 0tann>hlstory.sr ' 
glenn >proj1 > tests 



j»- glenn > history.sr 

f glenn >oldproj> tools f 



SET_SEARCH_RULES glenn > main.mylist 



MYLIST 



glenn 

glenn > mysubs 
glenn >proj1 > routines 
glenn >proj1 >tools 
glenn > oldproj > tools 
glenn>proj1 >tests 
glenn > tests 



RESULTING SEARCH LIST 



Setting a Search List from Nested Search Rules Files 
Using the -insert Keyword 

Figure 3-1 



-system 

The -system keyword allows you to change the placement of system rules 
in a search list. By default, PRIMOS automatically places the system 
rules at the beginning of the search list. To place the system rules 
elsewhere in the search list, you specify the -system keyword at the 
desired location. When you set the search list, the complete sequence 
of system rules is placed in your search list at the location indicated 
by the -system keyword. 
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If you set the search list using the SET_SEARCH_RULES command, it is 
necessary to suppress the automatic inclusion of the system rules at 
the top of the list. To suppress automatic inclusion of system rules, 
use the SET_SEARCH_RULES command -no_system option. If you set the 
search list using the SR$SSR subroutine, just specify the -system 
keyword at the desired location. You do not have to suppress inclusion 
of system rules at the beginning of the search list. 

The example in Figure 3-2 inserts the system rules at the location 
indicated by the -system keyword. The SET_SEARCH_RULES -no_system 
option suppresses inclusion of the system rules at the beginning of the 
list. 



glenn > main.command$.sr 



^-<0>search rule*>command$.sr 



cmdncO 

submaster 




I 



SYSTEM SEARCH RULES FILE 



SET_SEARCH_RULES glenn > main. command$ -no_system 



COMMANDS 



glenn 

glenn >mysub 

cmdncO 

sys> submaster 

glenn > tests 



RESULTING SEARCH LIST 



Setting a Search List With User and System Default 
Search Rules Using the -system Keyword 

Figure 3-2 
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If you do not suppress the prefacing of system rules (by using the 
SET_SEARCH_RHLES -no_system option) PRBJOS ignores the -system keyword, 
and places the system rules at the beginning of the file. 

Do not use the -system keyword in a search rules file for the ATTACKS 
search list. Instead, use the -added_disks keyword to perform the 
equivalent operation. 



-optional 

The -optional keyword specifies a rule that must te enabled before it 
can be used by PRDOS. In your search rules file, you write the 
-optional keyword and the rule that must be enabled on the same line, 
as shown in the following search rules file: 



glenn>tools 
-optional glenn>tests 
glenn>routines 



When you set a search list, all optional search rules are disabled. 
PRIMOS skips over those rules when searching the list. The 
LIST_SEARCH_RUUES command and most subroutines do not display the 
disabled search rules in the search list. For example, if you set a 
search list using the search rules file above, and then issue a 
LIST_SEARCH_RULES command for that search list, the following search 
rules are displayed: 



glenn>tools 
glenn>routines 



You can enable optional search rules in a search list by using the 
SRSENABL subroutine. When enabled, an optional search rule appears in 
the search list as an ordinary rule. For example, if you enable the 
glenn>tests optional search rule and then issue a IJ:ST_SEARCH_RULES 
command, the following search rules are now displayed: 



glenn>tools 
glenn>tests 
glenn>routines 



Optional search rules can be set in any search list, including system 
and administrator search lists. You can specify any search rule or 
search rule keyword as an optional search rule, except for the keywords 
-system and -insert. 
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Optional rules in a search list can be repeatedly enabled and disabled. 
One application of optional search rules is to establish search rules 
that are used only by a particular program. You enable the optional 
rules at the beginning of program execution and disable the optional 
rules at the end of program execution. For further details, refer to 
SR$ENABL in the Subroutines Reference Guide, Volume II. 



-added_disks 

The -added_disks keyword causes PRIMOS to search all of the added disk 
partitions. The -added_disks keyword is only used in the ATTACKS 
search list. When you set an ATTACKS search list, the set operation 
copies the -added_disks keyword from the search rules file into the 
search list. When PRIMOS uses the ATTACH! search list and encounters 
the -added_disks keyword, it searches all disk partitions added to the 
system. PRIMOS searches the added disks in the following sequence: 
all local disks in the order added, followed by all remote disks in the 
order added. 

Because the -added_disks keyword causes PRIMOS to search all added 
disks, it is normally specified as the last search rule in an ATTACKS 
search list. The -added_disks keyword searches all disk partitions, 
including those that have already been searched using previous ATTACKS 
search rules. 

The -added_disks keyword is the system default . To specify any other 
sequence of disks in an ATTACKS search list, you must suppress this 
default. One method is to place the -added_disks keyword at the end of 
your search rules file, then set the ATTACKS search list using the 
SET_SEARCH_RULES command with the -no_system option. For systems with 
many added remote disks, it is recommended that you do not include the 
-added_disks keyword In your ATTACKS search list. 



-static_mode_libraries 

The -static_mode_libraries keyword causes PRIMOS to search the 
static-mode libraries. The -static_jnode_libraries keyword is only used 
in the ENTRYS search list. When you set an ENTRYS search list, the set 
operation copies the -static_mode_libraries keyword from the search 
rules file into the search list. When PRIMOS uses the ENTRYS search 
list and encounters the -statio_mode_J. i.braries keyword, it searches the 
static-mode libraries for the desired entrypoint. Refer to the 
Programmer's Guide to BIND and EPFs for further details on the use of 
ENTRYS. 
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-prijmos_direot_entries 

The -primos_direct_entries keyword causes PRIMQS to search the PRIMOS 
system calls. The -primos_direct_entries keyword is only used in the 
ENTRY$ search list. Normally, this keyword is set as an administrator 
rule in the ENTRY$ search list. When PRIMOS uses the ENTRY$ search 
list and encounters the -primos_direct_entries keyword, it searches the 
PRIMOS system calls for the desired entrypoint. Refer to the 
Programmer's Guide to BIND and EPFs for further details on the use of 
ENTRY$. 



[origln_dir] 

The [origin_dir] keyword causes PRIMOS to search the user's origin 
directory (that is, the user's initial attach point). This keyword is 
executed when the search list is used. When you set a search list, the 
set operation copies the [origin_dir] keyword from the search rules 
file into the search list. When PRIMOS uses the search list and 
encounters the [origin_dir] keyword, it searches the user's origin 
directory. The [origin_dir] keyword can be used in all search rules 
files (including search rules files for administrator and system rules) 
with the exception of ATTACKS. 

The torigin_dir] keyword can be used as a complete search rule or as a 
component of a pathname in a search rule, as shown in the following 
sample search rules file: 

[origin_dir] 
glenn>tools 
torigin_dir] >tools 
glenn>subr 



[home_dir] 



The [home_dir] keyword causes PRIMOS to search the user's home 
directory (that is, the user's current attach point). This keyword is 
executed when the search list is used. When you set a search list, the 
set operation copies the [home_dir] keyword from the search rules file 
into the search list. When PRIMOS uses the search list and encounters 
the [home_dir] keyword, it searches the user's current attach point at 
the time of the search operation. The thome_dir] keyword can be used 
in all search rules files (including search rules files for 
administrator and system rules) with the exception of ATTACH$. Using 
[home_dir] in the ENTRY$ search list can produce unexpected results, 
and is therefore not recommended. 
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The [home_dir] keyword can be used as a complete search rule or as a 
component of a pathname in a search rule, as shown in the following 
sample search rules file: 

[home_dir] 
glenn>tools 
[home_dir] >tools 
glenn>subr 



[ ref erencing_dir ] 

The treferencing_dir] keyword causes PRIMOS to search a pathname 
supplied by the user. When you set a search list, the set operation 
copies the treferencing_dir] keyword from the search rules file into 
the search list. When the search list is used, the operation that uses 
the search list should also supply a pathname to substitute for the 
[referencing_dir] keyword. If an operation that uses the search list 
does not supply a pathname, PRIMOS ignores the treferencing_dir] 
keyword and proceeds to the next rule in the search list. The 
[referencing_dir] keyword can be used in all search rules files 
(including search rules files for administrator and system rules) with 
the exception of ATTACKS. 

The EXPAND_SEARCH_RULES (ESR) command and the OPSR$ and OPSRS$ 
subroutines have optional arguments that supply a pathname to the 
[referencing_dir] keyword. PRIMOS substitutes this pathname for every 
instance of [referencing_dir] in the search list and then performs the 
search operation. The [referencing_dir] keywords revert to null values 
at the completion of the search operation. 

Compilers that use the INCUIDES search list automatically supply values 
to the [referencing_dir] keyword. For further details concerning the 
use of [referencing_dir] in INCLUDES search lists, refer to the 
individual language manuals. 

The [referencing_dir] keyword can be used as a complete search rule or 
as a component of a pathname in a search rule, as shown in the 
following sample search rules file: 

[ ref erencing_dir ] 
glenn>tools 

[referencing_dir] >tools 
glenn>subr 
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ACCESSING SEARCH LISTS 

You can use search lists to conduct searches from the FRIMOS command 
environment, from CPL programs, or through subroutine calls from user 
programs. The five system-defined search lists are also accessible by 
specific system software. The ATTACKS search list can be accessed by 
other search lists. 



FRIMOS Command Environment 

The EXPAM3_SEARCH_RULES (ESR) command uses a search list to locate the 
requested item and returns the absolute pathname of the object to the 
user's terminal. When you issue an ESR command, you specify which 
search list should be used for the search. If you do not specify which 
search list to use, ESR selects a search list, based on the suffix of 
the sought item. If the object of the search is not located, ESR 
returns the value $ERROR$. The ESR command is further described in the 
PRIMOS Commands Reference Guide. 



CPL Programs 

EXPAim_SEARCH_RULES (ESR) can be issued as a CPL function from within a 
CPL program. The ESR CPL function has the same syntax and options as 
the ESR PRIMDS command. When issued as a CPL function, ESR returns the 
absolute pathname to a variable within the CPL program. 



Program Subroutines 

The search rules facility supports 18 search rule subroutines. Most of 
these subroutines perform operations on the search lists themselves. 
However, two subroutines (OPSR$ and OPSRS$) use the search rules to 
locate and open a file. These two subroutines can also check for the 
existence of a file system object and, under certain circumstances, 
create a new file system object if the specified object does not exist. 

The available search rule subroutines are as follows: 

Routine Function 

OPSR$ Locates a file using a search list and opens the 
file. Creates the file if the file sought does 
not exist. 

OPSRS$ Locates a file using a search list and a list of 
suffixes. Opens the located file or creates the 
file if it does not exist. 
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Routine Function 

SRSABSDS Disables an optional search rule. Used to 
disable rules that have been enabled using 
SR$ENABL. This subroutine absolutely disables an 
enabled rule, regardless of how many times the 
rule has been enabled. Compare with SR$DSABL. 

SR$ADDB Adds a rule to a search list before a specified 
rule. 

SR$ADDE Adds a rule to the end of a search list, or after 
a specified rule. 

SR$CREAT Creates a search list. 

SR$DEL Deletes a search list. 

SR$DSABL Disables an optional search rule that was enabled 
by SR$ENAHL. Disables a single SR$ENAEL 
operation. Compare with SRSABSDS. 

SRSENABL Enables an optional search rule. Enabled rules 
can be disabled using SR$DSAEL or SR$ABSDS. 

SRSEXSTR Determines if a search rule exists. 

SR$FR_LS Frees list structure space allocated by SR$HEST 
or SR$READ. 

SR$INIT Initializes all search lists to system defaults. 

SRSLIST Returns the names of all defined search lists. 

SR$NEXTR Reads the next rule from a search list. 

SR$READ Reads all of the rules in a search list. 

SR$REM Removes a search rule from a search list. 

SR$SETL Sets the locator pointer for a search rule. 

SR$SSR Sets a search list using a user-defined search 
rules file. 



These subroutines are further described in the Subroutines Reference 
Guide, Volume II. 
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ATTACKS Invoked by Other Search Lists 

For all search lists except ATTACKS, each search rule must contain a 
top-level directory name. These search rules can include or omit the 
disk partition name. If the partition name is omitted, PRIMQS 
automatically uses the ATTACKS search list to supply the partition name 
to the search rule. 

This search operation is performed as follows: During a search 
operation PRIMOS checks a rule in a search list and determines whether 
or not the rule contains a partition name. If it does not, PRIMOS goes 
to the ATTACKS search list and searches the first partition named in 
that list. If the top-level directory is not found on that partition, 
PRIMOS proceeds to the second disk, listed in ATTACKS , and so forth. 
When PRIMOS finds a disk that contains the top-level directory, it 
returns to the initial search list. 

This search procedure increases the power and flexibility of the search 
rules facility. It does, however, have two consequences that users 
should be aware of: 

• Duplicate top-level directory names can produce unexpected 
results, as shown in the following example: You are searching 
for glenn>mywork. Top-level directories named glenn are found 
on diskl and disk2. These disks are listed in that order in 
ATTACKS. The directory glenn that contains mywork is on disk2. 
In this case, the search operation uses ATTACKS to locate 
<diskl>glenn, then proceeds to search that directory for 
mywork. It doesn't find mywork in that directory and reports 
that mywork does not exist. Because the ATTACKS search 
completed successfully by finding <diskl>glenn, PRIMOS did not 
search <disk2>glenn. 

• Nonexistent top-level directories can cause performance 
problems. This is because PRIMOS must search every disk in the 
ATTACKS list for the nonexistent directory each time that the 
search list is used. If the ATTACKS search list contains 
several remote disks, this search time can be significant. 

If a search rule does not contain a partition name, and no ATTACKS 
search list is set, PRIMOS automatically searches all added disks for 
the required disk name. All local disks are searched first in the 
order added, then remote disks are searched in the order added. 
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This chapter describes, in detail, the initial, home, and current 
attach points, and then describes subroutines that are used to 
manipulate attach points. 



THE INITIAL ATTACH POINT 

When a new user is added to the system, the System Administrator or the 
Project Administrator specifies an initial attach point and usually 
creates an origin directory for the new user. 

PRBDS attaches the user's process to the origin directory during the 
login procedure; when the procedure terminates, the user's initial, 
home, and current attach points are all set to the origin directory, 
unless the login procedure itself (or an external program that it may 
call) has changed the home or current attach point, or both. 

During a terminal session, the user may reset his or her home and 
current attach points to the origin directory by issuing the ORIGIN 
command. Your program may also reset the home and current attach 
points by using the AT$CR subroutine. The AT$OR subroutine allows your 
program to reset just the current point or both the current and home 
attach points to the origin directory. Figure 4-1 illustrates the 
calling sequence for the AT$CR subroutine. 

If the toy argument is k$geth , both the home and current attach points 
• are reset to the origin directory. If the key argument is k$setc , only 
the current attach point is reset to the origin directory. 
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Reset Current (and, Optionally, Home) Attach Point to Origin Directory 



| KSSETH 
I K$SETC 



HALF 
INT 



AT$OR (key, code) 



HALF 
INT 



Standard 
• Error 
Code 



Calling Sequence of AT$CR 
Figure 4-1 
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An output argument, code , informs your program of the success or 
failure of the operation. If code is 0, the operation was entirely 
successful. Otherwise, code is always positive. After a call to AT$OR 
to attach to the origin directory, code may have one of many values. 
Volume of this series contains a comprehensive list of all standard 
file system error codes. Error codes specific to this operation are: 



Keyword Value Meaning 

E$NATT 7 No top-level directory attached. This 

error usually occurs only when the disk on 
which the origin directory resides has been 
removed from the system, as when a disk is 
shut down. Once a disk has been shut down, 
all origin directories residing on that 
disk and belonging to all currently 
logged-in users are lost. These users can 
reestablish their origin directories only 
by logging in after the disk is started up 
again. 

E$SHEN 121 The disk has been shut down. The disk on 

which the origin directory resides has been 
shut down by the system operator. The disk 
is no longer available for use, until the 
system operator uses the ADDISK command to 
add the disk again. After this is done, 
the user must log in again to reestablish 
his or her origin directory. 



THE HOME ATTACH POINT 

The home attach point essentially identifies the user's working 
directory. Initially, following user login, the home attach point is 
the same as the initial attach point. The user can change this by 
issuing the ATTACH command. 

Many system operations automatically reset the current attach point to 
the home attach point, as described below. To reset the current attach 
point to the home attach point from within your program, use the AT$HOM 
subroutine. Figure 4-2 illustrates the calling sequence for the AT$H0M 
subroutine. 



An output argument, code , informs your program of the success or 
failure of the operation. If code is 0, the operation was entirely 
successful. Otherwise, code is always positive. After a call to 
AT$H0M to attach to the home directory, code may have one of many 
values. Volume of this series contains a comprehensive list of all 
standard file system error codes. 
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Reset Current Attach Point to Home Directory 



AT$HOM (code) 



t 

HALF 

INT 



Standard 
- Error 
Code 



Calling Sequence of AT$HOM 
Figure 4-2 
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Error codes specific to the AT$HDM subroutine are: 



Keyword Value Meaning 

E$NATT 7 No top-level directory attached. This 

error usually occurs only when the disk on 
which the home directory resides has been 
removed from the system, as when a disk is 
shut down. Once a disk has been shut down, 
all home directories residing on that disk 
for all currently logged-in users are lost. 
These home directories can be reestablished 
by the users only by issuing an ATTACH 
command after the disk is started up again. 

E$SHDN 121 The disk has been shut down. The disk on 

which the home directory resides has been 
shut down (using the SHUTDN command as 
described in the System Operator's Guide, 
Volume II ). The disk is no longer 
available for use, until the system 
operator uses the ADDISK command to add the 
disk again. After this is done, the user 
must issue the ATTACH command again to 
reestablish his or her home directory. 



THE CURRENT ATTACH POINT 

The current attach point is essentially the program's working 
directory. Initially, the current attach point is the same as the 
initial and home attach points. A program can change the current 
attach point by calling one of many file system subroutines: 



Subroutine 
AT$ 



AT$ABS 



AT$ANY 



Use 

Attaches the current (optionally home) attach 
point to the directory specified by pathname. 
Similar to the ATTACH pathname command. 

Attaches the current (optionally home) attach 
point to the specified top-level directory on the 
specified disk partition. Similar to the ATTACH 
<partition > dirname command. 

Attaches the current (optionally home) attach 
point to the specified top-level directory on the 
first disk partition found to have the specified 
top-level directory. All local partitions are 
searched first; then, remote partitions are 
searched. Similar to the ATTACH dirname command. 
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Subroutine Use 

AT$HDM Attaches the current attach, point to the home 
directory, as described earlier in this chapter. 
Similar to the ATTACH command. 

AT$CR Attaches the current (optionally home) attach 
point to the origin directory, as described 
earlier in this chapter. SJjnilar to the ORIGIN 
command. 

AT$REL Attaches the current (optionally home) attach 
point to the specified lower-level directory of 
the current current directory. Used to attach 
downward in a directory tree. Similar to the 
ATTACH *>dirname command. 



All of the above subroutines replace an obsolete subroutine named 
ATCH$$ that performed all of the attach functions in one (rather 
complicated) interface. The subroutines listed above are described 
later in this chapter; the ATCH$$ subroutine is described in detail in 
Appendix A of of the Subroutines Reference Guide , Vol. II. 



Operations That Reset the Current Attach Point 

Because the current attach point is used in so many file system 
operations, it is often reset even when errors occur. For example, if 
a call to ATS is made to set the current attach point to 
FR0IX)>FINGER>PC0D, and the FINGER lower-level directory does not exist 
in the FRC8D0 directory, an error code of e$fntf (Not found) is 
returned, and the current attach point is reset to the home directory, 
independent of what it was before the call was made. 

Similarly, a mistyped command resets the current attach point to the 
home directory. In fact, the only way to avoid resetting the current 
attach point while at PRIMOS command level is to use only internal 
commands, such as OPEN, STATUS, DJMP_STACK, and so on. (The PRIMOS 
Command Reference Guide lists internal commands.) 

Commands such as LD, DELETE, COPY, EMACS, and USAGE reset the current 
attach point. In most cases, resetting the current attach point is 
usually not a problem. Resetting the current attach point is a problem 
if a program activation has been suspended (such as via CDNTROL-P) just 
when the current attach point is different from the home attach point. 
In this case, restarting the suspended program may produce irrational 
behavior. Programs that make heavy use of the current attach point can 
expect to encounter problems resulting from program interruptions; 
even programs that do not explicitly use the current attach point can 
possibly encounter problems when calling subroutines that handle 
pathnames (such as SRSFX$), because these subroutines use the current 
attach point and may also be interrupted. 
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In addition, anytime a pathname is processed by the file system, the 
current attach point is reset to the home directory. For example, if 
the DIR$GR subroutine, described in Chapter 6, DATA STORAGE AND 
RETRIEVAL, is called with the pathname FRODO>THUMB, the current attach 
point is implicitly reset to the home directory. 

File system subroutines that accept filenames but not pathnames assume 
that the specified file is in the current directory. Similar 
subroutines perform their operations in the current directory, although 
they do not actually accept filenames as arguments. In both cases, 
these subroutines are frequently referred to as file system primitives . 
The use of these primitives rarely changes the current attach point. 
Among the PRIMOS file system primitives are the following subroutines: 



ACSRVT CNAM$$ 0OMI$$ 00M0$$ FIL$DL GPAS$$ 
GPATH$ PHANT$ FHNTM$ RESTS $ RESU$$ SATR$$ 
SAVE$$ SPAS$$ SRCH$$ 



Note 

CREA$$ and CREPW$, which accept only filenames, are considered 
obsolete at PRIMOS Rev. 20.2. Although CREA$$ and CREPW$ are 
still supported, programs should use DIR$CR, which accepts 
pathnames, beginning with Rev. 20.2. 



All other subroutines that operate either explicitly or implicitly on a 
pathname (any file system name containing at least one < or > 
character) reset or change the current attach point. 



FUNCTIONS USED TO MANIPULATE ATTACH POINTS 

In addition to the subroutines described earlier in this chapter, six 
subroutines are provided to allow a running program to manipulate the 
user's attach points. These are: 

• The AT$ subroutine, which attaches to a pathname 

• The AT$ABS subroutine, which attaches to a top-level directory 
on a specified disk partition 

• The AT$ANY subroutine, which attaches to a top-level directory 
on any started-up disk partition 

• The AT$REL subroutine, which attaches down to a subordinate 
directory 

• The GPATHS subroutine, which returns the complete pathname of 
the initial, home, or current directories 



4-7 Second Edition 



ADVANCED PROGRAMMER'S GUIDE, VOLUME II: FILE SYSTEM 



• The SRCH$$ subroutine, which opens the current directory for 
reading 



The ATS Subroutine 

To attach to a specific directory by pathname, use the ATS subroutine. 
The ATS subroutine parses a pathname, and calls the ATSABS, ATSANY, 
ATSHOM, and ATSREL subroutines (described below) to perform the actual 
attaching. 

The ATS subroutine may be used to change only the current directory or 
both the home and current directories. It may return any of the error 
codes that the other four subroutines can return, with one additional 
error code — eSitre (Illegal treename). This error code indicates an 
invalid pathname. 



The subroutines called by ATS depend on the form of the pathname, 
several forms and their corresponding implementations are: 



The 



Form 



Causes 



<disk>. 



dir 
dir>. . 



>. . . 



A call to ATSABS by ATS to attach to the specified 
disk partition followed by calls to ATSREL to 
attach to directories following the < disk > portion 
of the pathname 

A call to ATSANY by ATS to attach to the first 
directory specified in the pathname followed by 
subsequent calls to ATSREL to attach downward 

A call to ATSHOM by ATS to attach to the home 
directory followed by calls to ATSREL to attach 
downward 



(null) A call to ATSHCM by ATS 
directory 



to attach to the home 



Note 

PRIMOS treats a single (simple) object name in one of two ways, 
depend i ng upon whether or not the object name is a directory to 
which the user is to be attached. 

When attaching to a directory, a simple object name identifies 
a top-level directory that is to be searched for. In other 
cases, a simple object name identifies a file in the current 
directory. 
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This distinction is seen when comparing the following two 
PRBJOS commands: 



ATTACH FRCEO 
SLIST FRCCO 



The ATTACH command searches for a top-level directory named 
FRODO. The SLIST command searches for a file named FRCDO in 
the home (current) directory. (When the SLIST command is 
issued, the current attach point is reset to the home directory 
by the operation of searching the command directory, CMENCO, 
for the SLIST program.) 



Figure 4-3 illustrates the calling sequence of ATS. 



The AT$ABS Subroutine 

To attach to a top-level directory on a specific disk partition, use 
the AT$ABS subroutine. This subroutine allows you to specify the disk 
partition by using: 

• The name of the partition 

• The partition on which the current directory resides 

• The partition corresponding to logical disk 

• The partition corresponding to a particular logical disk number 
When your program calls AT$ABS, it provides: 

• A key that specifies whether the home attach point is to be set 

• The identity of the top-level directory's partition, in any of 
the forms listed above 

• The name of the top-level directory itself 

The AT$ABS subroutine attempts to set the current attach point to the 
specified top-level directory on the specified partition, and returns a 
code indicating whether the operation was successful. If the operation 
fails, no changes are made to the attach points. If the operation 
succeeds, the home attach point is also set to the current attach point 
if specified by the key. 

Figure 4-4 illustrates the calling sequence of the AT$ABS subroutine. 
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Attach to Directory by Pathname 



K$SETH | 
K$SETC I 



Pathname of 
Target Directory 
(Null String Means 
Home Directory) 



HALF < = 128 
INT STRING 

1 I 

AT$ (key, name, 


code) 

1 






1 

HALF 
INT 



Standard 

Error 

Code 



Calling Sequence of AT$ 
Figure 4-3 
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Attach to Top-level Directory of Specified Partition 



Name or Logical Disk 
Number of Partition - 
(Such as 'PUBS' or 
'27'), Null String 
(Logical Disk 0), or 
'*' (Disk of Current 
Attach Point) 



K$SETH 
K$SETC 



Top-level Directory 
Name With Optional 
Password (Separated by 
One Space), or Null String 
(Implying MFD) 



HALF < = 32 < = 39 

INT STRING STRING 

1 I I 

AT$ABS (key, partition, directory, code) 



HALF 
INT 



Standard 

Error 

Code 



Calling Sequence of AT$ABS 
Figure 4-4 



4-11 



Second Edition 



ADVANCED PROGRAMMER ' S GUIDE, VOLUME II: FILE SYSTEM 



The Key : Your program sets the ke^ argument to one of the following: 

Keyword Value Meaning 

K$SETC Set only the current attach point. 

K$SETH 1 Set both the current and home attach 

points. 

The Partition : Your program passes the partition on which the 
top-level directory resides as a character string. A null partition 
name specifies logical disk (the command device). A partition name 
of * specifies the partition on which the current current directory 
resides. A character string that is an unsigned octal number specifies 
the logical disk number. Otherwise, the partition name identifies the 
desired partition. 

The Top-level Directory : Your program passes the name of the top-level 
directory to attach to as a character string. To specify a password, 
append it to the directory name with a single space separating the 
directory name and the password. 

If your program passes a null directory name, AT$ABS attaches to the 
MFD of the desired partition. 

The Error Code : An output argument, code , informs your program of the 
success or failure of the operation. If code is 0, the operation was 
entirely successful. Otherwise, code is always positive. After a call 
to AT$ABS to attach to a top-level directory, code may have one of many 
values. Volume of this series contains a comprehensive list of all 
standard file system error codes. Error codes specific to this 
operation are: 

Keyword Value Meaning 

E$BPAR 6 Bad. parameter. The length of the directory 

name as passed by the calling program is a 
negative number or is greater than 39 
(including an optional directory password) . 

E$NATT 7 No top-level directory attached. This 

error can occur only when the partition 
name is * and the partition on which the 
current directory resides is removed from 
the system, as when a disk is shut down. 
Use one of the subroutines described in 
this chapter to reestablish a current 
attach point. 
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Keyword Value Meaning 

E$FNTF 15 Not found. The specified partition does 

not exist, or the specified directory does 
not exist on that partition. 

E$BNAM 17 Illegal name. The partition name must be 

between and 32 characters in length. The 
directory name must also be between and 
32 characters in length (inclusive), 
optionally followed by a single space and a 
password from 1 to 6 characters long 
(inclusive) . 



Example : The following PL/I statement sets the home and current attach 
points to the directory named ORANGE on the partition named RHYMES: 

call at$abs(k$seth, 'RHYMES' , 'ORANGE' .code); 



The AT$ANY Subroutine 

To attach to a top-level directory on any disk partition, use the 
AT$ANY subroutine. AT$ANY scans all started-up disks for the specified 
top-level directory. It scans local partitions first, in logical disk 
order, and then scans remote partitions in logical disk order. Use the 
STATUS DISKS command to determine the logical disk order for your 
system. 

When calling ATS ANY, your program provides: 

• A key that specifies whether the home attach point is to be set 

• The name of the top-level directory 

The AT$ANY subroutine attempts to set the current attach point to the 
specified top-level directory on the first partition it finds that has 
such a directory. It returns a code indicating whether the operation 
was successful. If the operation fails, no changes are made to the 
attach points. If the operation succeeds, the home attach point is 
also set to the current attach point if specified by the key. 

Figure 4-5 illustrates the calling sequence of the ATSANY subroutine. 



4-13 Second Edition 



ADVANCED PROGRAMMER ' S GUIDE, VOLUME II: FILE SYSTEM 



Attach to Top-level Directory of Any Partition 
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Figure 4-5 
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The Key : Your program sets the key argument to one of the following 



Keyword Value 
KSSETC 
K$SETH 1 



Meaning 

Set only the current attach point. 

Set both the current and home 
points. 



attach 



The Top-level Directory : Your program passes the name of the top-level 
directory to attach to as a character string. To specify a password, 
append it to the directory name with a single space separating the 
directory name and the password. 



The Error Code : An output argument, code , informs your program of the 
success or failure of the operation. If code is 0, the operation was 
entirely successful. Otherwise, code is always positive. After a call 
to AT$ANY to attach to a top-level directory, code may have one of many 
values. Volume of this series contains a comprehensive list of all 
standard file system error codes. Error codes specific to this 
operation are: 



Keyword Value Meaning 

E$BPAR 6 Bad parameter. The length of the directory 

name as passed by the calling program is a 
negative number or is greater than 39 
(including an optional directory password). 

E$BNAM 17 Illegal name. The syntax of the directory 

name as supplied by the calling program is 
not correct. The directory name must be 
between and 32 characters in length, 
optionally followed by a single space and a 
password. See the Prime User's Guide for a 
description of the legal syntax for 
objectnames. 

E$NFAS 189 Top-level directory not found or 

inaccessible. The specified directory 
could not be found, or resides on a disk 
partition that cannot be accessed by the 
user. 
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Example : The following PL/I statement sets the home and current attach 
points to the directory named ORANGE on the first partition found to 
contain a directory named ORANGE: 



call at$any(k$seth, 'ORANGE' .code); 



The AT$REL Subroutine 

Use the AT$REL subroutine to attach down to a directory that is 
subordinate to the current directory. The subroutine searches through 
the current directory for the specified lower-level directory, and 
attaches to it as the new current (and optionally home) directory. 

When calling AT$REL, your program provides: 

• A key that specifies whether the home attach point is to be set 

• The lower-level directory to be attached to 

The AT$REL subroutine attempts to set the current attach point to the 
specified lower-level directory of the current directory, and returns a 
code indicating success or failure. If the operation fails, the attach 
points are not changed. If the operation succeeds, the home attach 
point is also set to the current attach point if specified by the key. 

Figure 4-6 illustrates the calling sequence of the AT$REL subroutine. 

The Key : Your program sets the key argument to one of the following 

Keyword Value Meaning 

K$SETC Set only the current attach point. 

K$SETH 1 Set both the current and home attach 

points. 

The Lower-level Directory : Your program passes the name of the 
lower-level directory to attach to as a character string. To specify a 
password, append it to the lower-level directory name with a single 
space separating the lower-level directory name and the password. 

The Error Code : An output argument, code , informs your program of the 
success or failure of the operation. If code is 0, the operation was 
entirely successful. Otherwise, code is always positive. After a call 
to AT$REL to attach to a lower-level directory, code may have one of 
many values. Volume of this series contains a comprehensive list of 
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Attach to Subdirectory of Current Directory 
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all standard file 
operation are: 



system error codes. Error codes specific to this 



Keyword Value 
E$BPAR 6 



E$NATT 



E$BNAM 



17 



Meaning 

Bad parameter. The length of the 
lower-level directory name as passed by the 
calling program is a negative number or is 
greater than 39 (including an optional 
lower-level directory password). 

No top-level directory attached. This 
error can occur only when the partition on 
which the current directory resides is 
removed from the system, as when a disk is 
shut down. Use one of the AT$xxx 
subroutines to reestablish a current attach 
point. 



Illegal name. The 
lower-level directory 
the calling program is 
lower-level directory 
and 32 characters in 



syntax of the 
name as supplied by 

not correct . The 
name must be between 

length, optionally 



followed by a single space and a password. 
See the Prime User's Guide for a 

for 



description 
objectnames . 



of the legal syntax 



Example : The following PL/I statement sets the home and current attach 
points to the lower-level directory named JUICE of the current 
directory: 



call at$rel(k$seth, 'JUICE' .code); 



The GPATH$ Subroutine 

It is sometimes useful for your program to be able to determine the 
full pathname of the initial, home, or current directories. The GPATH$ 
subroutine provides this function. This subroutine is also capable of 
determining the full pathname of a file open on any file unit, 
inoi n^ing the command output unit. File numbers for member files 
within segment directories are returned when appropriate. 
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To determine the full pathname of one of the three directories, your 
program calls GPATH$ and provides it with: 

• A key that specifies which directory pathname is to be obtained 

• The size of the buffer into which the pathname is to be stored 

The GPATH$ subroutine determines the appropriate directory pathname and 
returns to your program: 

• A buffer containing the resulting pathname 

• The actual length of the pathname 

• An error code indicating whether the operation was successful 

Figure 4-7 illustrates the calling sequence for the GPATH$ subroutine 
to determine the pathname of one of the three attach points. 

The Key : Your program sets the key argument to one of three values: 

Keyword Value Meaning 

K$C0RA 2 Determine the pathname of the current 

directory. 

K$HCMA 3 Determine the pathname of the home 

directory. 

K$INIA 4 Determine the pathname of the initial 

directory. 



Maximum Size of the Returned Pathname : Your program sets the 
ma3L.name_len argument to the size of the name argument in bytes. If 
the resulting pathname is longer than max_name_len characters, the 
operation fails, and an error code of e$bfts is returned. 



The Returned Pathname : The GPATH$ subroutine sets the name argument to 
the resulting pathname if the operation succeeds ( code is 0). GPATH$ 
stores the operational length of the returned pathname in name_len . No 
characters beyond character number name__len in name contain valid data. 



The Actual Length of the Returned Pathname : GPATH$ sets the name_len 
argument to the length of the resulting pathname in bytes if the 
operation sucoeeds ( code is 0). 
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Determine Pathname of an Attach Point 
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The Error Code : An output argument, code , informs your program of the 
success or failure of the operation. If code is 0, the operation was 
entirely successful. Otherwise, code is always positive. After a call 
to GPATH$ to determine the pathname of an attach point, code may have 
one of many values. Volume of this series contains a comprehensive 
list of all standard file system error codes. Error codes specific to 
this operation are: 



Keyword Value Meaning 

E$NATT 7 No top-level directory attached. This 

error usually occurs only when the 
directory to which the user is attached is 
removed from the system, as when a disk is 
shut down. Use one of the subroutines 
described in this chapter to reestablish a 
current attach point. 

E$BFTS 35 Buffer too small. The supplied buffer is 

too small to hold the information. The 
buffer argument contains no useful data. 



Example : The following PL/I statements display the full pathname of 
the home directory: 

call gpath$ (k$homa,0, pathname, 80, pathlen, code); 
if code=0 then call t nou( pathname, pathlen); 

else call errpr$(k$irtn, code, 'Cannot get home pathname' ,24, 
'MYPROtaiAM',9) 



The SRCH$$ Subroutine 

Use the SRCH$$ subroutine to open the current directory. When calling 
SRCH$$, your program provides: 

• An indicator that the current directory is being opened 

• A key that specifies how the directory is to be opened 
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The SRCH$$ subroutine attempts 
returns to your program: 



to open the current directory and 



An error code indicating whether the operation was successful 

A file unit number that identifies the open directory. This 
number is used when reading directory entries. 



• The file type, indicating the type 
(currently always top-level directory) 



of file just opened 



This section describes the input and output parameters that apply when 
calling SRCH$$, and then shows a sample call to SRCH$$. Figure 4-8 
illustrates the calling sequence of the SRCH$$ subroutine to open the 
current directory. 



The Error Code : An output argument, code , informs your program of the 
success or failure of the operation. If code is 0, the operation was 
entirely successful. Otherwise, code is always positive. After a call 
to SRCH$$ to open the current directory, code may have one of many 
values. Volume of this series contains a comprehensive list of all 
standard file system error codes. Error codes specific to this 
operation are: 



Keyword Value 
E$NATT 7 



E$NRIT 



10 



Meaning 

No top-level directory attached. This 
error usually occurs only when the 
directory to which the user is attached is 
removed from the system, as when a disk is 
shut down. Use one of the subroutines 
described in this chapter to reestablish a 
current attach point. 

Insufficient access rights. The user does 
not have List access to the current 
directory. 



Example : The following example shows how a FORTRAN program opens the 
current directory for reading: 



CALL SRCH$$(K$REAmK$GETU,K$OTRR,0, UNIT, TYPE, CODE) 
IF (0ODE.NE.0) GO TO 1000 



1000 CALL ERRFR$(K$IRTN,OODE, 'Current directory ', 15 , 'MYPROGRAM' ,9) 

RETURN 
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Open Current Directory 
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QUESTIONS AND ANSWERS ABOUT ATTACH POINTS 

This section answers scans typical questions about attach points. 



• If the current attach point gets reset by a mistyped command, or by 
the execution of a non-internal command, how does this affect my 
running program? 

If a user quits (by typing OONTROL-P) while running a program, resets 
the current attach point by mistyping a command or executing a 
non-internal, command, and then restarts the program (by using the START 
command), the program may not continue working properly; its behavior 
when it resumes execution may be unpredictable, because it is suddenly 
performing file system operations in a different directory than 
intended. This is the case only if the user happened to quit while the 
program was using the current attach point separately from the home 
attach point. 

Attach points are not a part of the recursive command environment. You 
must consider this when you write programs that tend to disassociate 
the home and current attach points while allowing the user to quit. 

Even a call to SRSFX$ or CP$ can involve the specific use of the 
current attach point. (For example, calling CP$ to invoke DELETE 
causes an attach to CMDNCO to search for the DELETE program.) Because 
these subroutines are also interruptible, they may not continue 
execution properly if the current attach point is reset during an 
interruption, and improper execution of these subroutines may affect 
the operation of your program. 



• Can I use the GPATH$ subroutine to record my current attach point 
during a quit, and then when the user types START, call AT$ with 
the pathname returned by GPATH$ to preserve my attach point? 

Yes, with the following caveat: the pathname returned by GPATH$ 
contains no passwords. If your system is using password directories, 
it is possible that the mechanism proposed by this question might 
complicate matters, but if your system uses ACL directories throughout, 
then the proposed solution should work. 

There are two points to consider: 

• Make certain that the mechanism not only catches the original 
CDNTROL-P, but also catches the subsequent START command. The 
recommended way to do this is to resignal the QUITS condition 
from within the handler for QUITS. The Subroutines Reference 
Guide , Vol. Ill describes the condition signalling mechanism. 

• The access to the specified directory is recalculated whenever 
the mechanism is engaged. This is rarely a problem, but it is 
possible that the attempt to reattach to the current directory 
could fail due to insufficient access, whereas the original 
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Text Storage and 
Retrieval 



Many applications must be able to store and retrieve text strings on 
disk. Under PRIMOS, text strings consist of 8-bit characters in ASCII 
format . Each text string is considered to be a line of text . A text 
file consists of one or more lines of text. This chapter describes how 
programs create and operate on text files. 

Using PRIMOS, text storage and retrieval is straightforward. PRIMOS 
offers two methods of organizing lines of text on disk: 

• Variable-length records 

• Fixed-length records 

Each method of organization has advantages and disadvantages, described 
later in this chapter. PRBDS provides a unified interface to both 
types of files. In particular, the opening and closing of 
variable-length record and fixed-length record files is identical. The 
only difference is in the way data are actually read and written to the 
file. 

This chapter describes: 

• The differences between variable-length record files and 
fixed-length record files 

• How to open, extend, truncate, and close text files 

• How to read and write variable-length files 
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• How to read, write, and position fixed-length record files 

• The format of a variable-length record file 

• The format of a fixed-length record file 

This chapter closes with questions and answers about text files. 

SUBROUTINES FOR ACCESSING FILES 

The subroutines most often used when accessing text files are: 



Subroutine 



SRCH$$ 



SRSFX$ 



SGDSOP 
RDTiTWS 



WTLIN$ 



FRWF$$ 



Use 



Accepts a filename; opens, closes, deletes, 
changes access on, or verifies the existence of 
the file as requested by the key. Most commonly 
used to open and close files. 

Allows the calling program to specify a list of 
legal file suffixes in order to find a file with 
one of them. Each supplied suffix is appended to 
the base pathname, until the file is found or the 
list of suffixes is exhausted. This subroutine 
is -used by Prime software such as the RESUME 
command. 



Opens a file within a segment directory, 
segment directory must already be open. 



The 



Reads a line from an open variable-length record 
file, returning a fixed-length record buffer. 
The buffer is appropriately padded with spaces 
(240 octal). 

Writes a fixed-length record to an open 
variable-length record file. The length of the 
lin e is calculated by subtracting the number of 
trailing spaces (240 octal) from the length of 
the record. 

Used to truncate a file after writing it, in case 
the file is to be made shorter. For fixed-length 
record files, PR¥F$$ is also used to read, write, 
and position the file, as described later. 



All of these subroutines are thoroughly described in Volume II 
Subroutines Reference Guide. 



of the 
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DIFFERENCES BETWEEN VARIABLE-LENGTH AND FIXED-LENGTH RECORD FILES 

The organization of data within a file is defined by the program or 
programs that vise the file. PRIMOS does not maintain a description of 
the contents of any file. This allows flexibility in accessing files, 
because one program can treat a file as a collection of li n es of text, 
while another program can treat the same file as binary data. 

All programs that vise a file must agree on the organization of data 
within the file, because PRIMOS does not impose restrictions on the 
access method. This means that all programs must know whether a text 
file consists of variable-length records or fixed-length records when 
operating on text files. 

Therefore, you should decide early in any project whether to use 
variable-length records or fixed-length records. This will prevent 
confusion and program misbehavior. If such a decision cannot be made 
early enough, you should build a small subroutine library that can 
perform fixed-length operations on variable-length record files, and 
vice versa. You will rarely need such a subroutine library, however, 
because the advantages and disadvantages of the two organizations are 
so distinct. 



Variable-length Records 

Text files under PRIMOS normally consist of variable-length records. 
Each line of text in a file is terminated by a new-line character, 
ASCII LF (212 octal). The lengths of lines in the file vary from to 
an application-defined maximum. No prefix defining the record length 
is present; the new-line character delimits each record. 

Variable-length records offer the following advantages: 

• All Prime-supplied utilities that operate on text files accept 
variable-length records. Such utilities include SLIST, ED, 
EMACS, RUNOFF, SPOOL, and others. Only a few utilities, such as 
SORT, support fixed-length records. 

• Using variable-length records visually saves disk space. This is 
true when the lengths of lines in a file vary, or when three or 
more contiguous spaces (a space is 240 octal) occur frequently 
in the file. 

• There is no inherent limit to the length of a line in a 
variable-record file. Each particular application limits the 
operational length of lines in a text file to a specific 
quantity. This is also true of Prime-supplied utilities. The 
maximum line length in ED is different from that of EMACS, for 
example. 
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• The length of each line in a variable-record file is defined by 
a new-line character that follows it. Thus, a utility needs no 
information outside the file to use the file. On the other 
hand, any program that operates on a fixed-length record file 
roust know the record size of the file. 

Variable-length record files are sometimes referred to as compressed 
files. The term "compressed" refers to the compression of contiguous 
spaces. Another term, uncompressed , identifies a similar file format 
that does not include space compression. PRIMOS itself cannot 
distinguish between compressed and uncompressed files; your 
application must make this distinction. 



Fixed-length Records 

The alternate organization of text files under PRIMOS stores lines of 
text in fixed-length records. Here, the length of each record, or line 
of text, is known by the program using the file. Records are stored 
side-by-side in the file, with no intervening control information (such 
as a new-line character). 

Fixed-length records offer the following advantages: 

• Accessing a particular record is significantly faster when all 
of the records are fixed-length, since the location of the 
record is defined by only two variables — the record length for 
the file and the record number to be accessed. A 
variable-length record file must be searched sequentially until 
the desired record is found. 

• There are no restrictions on the character set. Characters such 
as the ASCII line feed (212 octal), DC1 (221 octal), and null 
(000 octal) can be read and written without any special 
consideration. 

• The execution speed of a program that expects records to contain 
fixed-length fields of information may be superior when 
fixed-length records are used. Fixed-length records can be read 
directly into PL/I structures or FORTRAN EQUIVALENCE areas 
without going through an intermediate parsing stage (as is 
necessary when reading variable-length records). 

• Programs that use f raed-length record data can often be more 
easily moved from one large-scale computer system to another. 
Fixed-length record organization has been in use for 
approximately a century, beginning with the punched card. 
Variable-length record organization is comparatively recent, and 
is still the second choice in languages such as COBOL, FORTRAN, 
and PL/I. 
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Hybrid Approaches 

As described previously, PRIMOS itself places no restrictions on the 
organization of data in a file. It is up to the programs that access 
the file to use the same access method on a file. Therefore, it is 
possible to construct hybrid file organizations that include advantages 
from both the fixed-length and variable-length record approaches. 

For example, if you use fixed-length records separated by an ASCII LF 
(212 octal) and a NUL (000 octal) byte, you will be able to display a 
fixed-length record file using SLIST. (It cannot be edited by using ED 
or EMACS, however.) 

To solve the problem of having to hard-code the record length into 
programs that use fixed-length records, the first two bytes of a file 
can be defined to contain the length of records in the file in bytes. 
However, this prevents the file from being directly sorted by Prime's 
SORT facility — when sorting fixed-length record files, SORT will not 
be expecting the first two bytes to contain such information. 

You may decide to have a variable-length record file to save disk 
space, using the PL/I language as a model. You can represent the 
individual records as PL/I CHARACTERS) VARYING variables, rather than 
ending each record with a new-line code. This has two disadvantages. 
First, it renders such files inaccessible via PRIMOS utilities such as 
SLIST, ED, and EMACS. Second, records would presumably not be written 
rising space compression techniques, and therefore one might take up 
extra disk space. The important advantage of this approach is that of 
fixed-length records; the entire character set may be used within each 
record. 

Although you can use approaches such as those described above instead 
of the variable-length and fixed-length record organizations, such 
approaches are not described in this book. If you find that you need a 
nonstandard organization for a text file, you must treat the file as a 
data file. The manipulation of data files is described in Chapter 6, 
DATA STORAGE AND RETRIEVAL. 



Maximum Length of a File 

Currently, the maximum number of characters that can be stored in one 
file under PRIMOS is 465 million. This assumes a single file stored on 
a 30-head partition residing on a 675MB disk drive (also known as a 
600MB disk), with the minimal housekeeping and directory information in 
the partition. 
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HOW TO OPEN, EXTEND, TRUNCATE, AND CLOSE TEXT FILES 
To read, a text file, your program normally: 

1. Opens the file for reading. 

2. Reads the file until the end of file is reached. 

3. Closes the file. 

To write a text file, your program normally: 

1 . Opens the file, for writing . 

2. Positions the file to end-of-file if new data is to he written 
to the end of the file; otherwise, your program will overwrite 
the existing data. 

3. Writes the file, automatically extending the file length when 
necessary. 

4. Truncates the file at the current position to insure that old 
data originally in the (longer) file is deleted. 

5. Closes the file. 

PRIMOS does not Impose restrictions on the order of these operations 
except that your program must open a file before it can read, write, 
extend, or truncate the opened file. 

The subjects of this section are how to open, position to the end of, 
truncate, and close a text file. The subsequent two sections describe 
how to actually read and write text files. 

Opening a File 

Before your program can access data in a file, it must open the file. 
Your program opens a file by using the SRSFX$, SGD$OP, or SRCH$$ 
subroutines. When your program calls these subroutines, it provides: 

• The name of the file to be opened. 

• A key that specifies how the file is to be opened. 
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The SRSFX$, SGDSOP, or SRCH$$ subroutine attempts to open the specified 
file and returns the following information to your program: 

• An error code indicating whether the operation was successful. 

• A file unit number that identifies the open file. Your program 
uses this number when performing operations (such as read and 
write) on an open file. 

• The file type, indicating the type of file just opened 
(including SAM, DAM, GAM, SBGSAM, SEGDAM, and Directory). 

Additional information returned by SRSFX$ is not relevant to this 
description. 

This section contains the input and output parameters applicable when 
you call SRSFX$, SGD$OP, and SRCH$$, and shows a sample call to SRCH$$. 
Figure 5-1 illustrates the calling sequence of SRSFX$ to open a file; 
Figure 5-2 illustrates the calling sequence of SGD$OP; Figure 5-3 
illustrates the calling sequence of SRCH$$ to open a file. 



The Name of the File : The rules for the filename depend on the system 
subroutine being called. 

Your program may supply a pathname if it is using SRSFX$. The pathname 
may identify segment directory members (such as FRED>XYZ . SEGX)) . 

For SGDSOP, your program must first position the segment directory to 
the desired entry by using SGER$$; then, your program calls SGD$OP, 
providing the file unit number of the open segment directory. 

When calling SRGH$$, the filename must be an objectname; that is, it 
cannot contain a > symbol. SRCH$$ searches the current directory for 
the specified file system object. 



The Key : In the case of SRSFX$ and SRGH$$, your program sets key as 
follows: 



key = action + newf ile + K$GETU 
For SGD$OP, your program sets key as follows: 
key = action 
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Open a File, With Possible Suffix 



Pathname of 
Object to Open 



K$READ \ 
K$WRIT } 

k$rdwr) 

j K$NSAM \ 

+ \k$ndam) 

+ KSGETU 



Number of Suffixes 
in suffixes Array 
(0 Means No Suffix 
Processing) 



Array of 

-Desired 

Suffixes 



< =32 

HALF < = 1S8 HALF^ STRING 

INT STRING INT "^ ARRAY 

I I I I 

SRSFX$ (key, name, unit, type, num suffixes, suffixes, basename, suffix used, code) 

111 I 

HALF HALF HALF < = 32 

INT INT INT STRING 



I 
HALF 

INT 



[ARRAY(2)] FTN/PMA 
only* 



File 
Type 



File Unit 
Number 



L [ 



(1): Termination Character Position 

(2): Length of Pathname"! 
(characters) J 



- FTN/PMA only* 



I 

HALF 
INT 

^ Standard 
Error 
Code 



L» Index Into suffixes 
of Suffix Used 
(matched); Means 
Null Suffix 



Final Component of name 
Without Suffix Used; Useful 
When Appending Another Suffix 



Side Effects: May reset current attach point. 

* Function value is returned in L-register; typically, you need only to declare as HALF INT, 
because first datum is all you need and is in A-register. Otherwise, you must declare it as 
FULL INT to make it work. 



Calling Sequence of SRSFX$ to 
Open a File 



Figure 5-1 
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Open Member of Segment Directory 



Unit Number 
of Segment 
Directory 



K$READ 
K$WRIT 
K$RDWR| 
K$VMR 



-10000 
(Find Available 
Unit Number) 
1<n<126 
(Use this Unit 
Number) 



HALF HALF 
INT INT 



HALF 
INT 



HALF 
INT 



Type of Newly Created File: 

K$NSAM 
K$NDAM 
K$NSGS 
K$NSGD 
K$NCAM 



I \ \ \ 

SGD$OP (key, seg-unit, file-unit, type, new-type, code) 



HALF 
INT 



HALF 
INT 



HALF 
INT 



Unit Number 
Member Opened On 



Standard 

Error 

Code 



Type of File Opened 



Value 


1 
2 
3 

7 



Type 

SAM File 

DAM File 

SAM Segdir 

DAM Segdir 

CAM File 



Side Effects: If seg-unit is at end of segment directory and key is K$WRIT or 
K$RDWR, SGD$OP attempts to automatically extend segment 
directory by one entry, which also repositions seg-unit to new 
end-of-segdir position; otherwise, size of segment directory 
and position of seg-unit remain unchanged. 



Calling Sequence of SGD$OP 
Figure 5-2 
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Open File in Current Directory 



K$BKUP ^ 
K$READ 
K$WRIT 
K$RDWR 

(KSNSAMl 
+ }K$NDAM) 

+ K$GETU 



Name of 
Object 



t t t 

HALF 32 -^ HALF 
INT STRING" v INT 



Length of 
Object Name 
(characters) 



SRCH$$ (key, name, name__len, unit, type, code) 

\ \ 1 



HALF HALF HALF 
INT INT INT 



File 

Unit -*- 
Number 



Standard 
-+■ Error 
Code 



Object 
'Type 



Calling Sequence of SRCH$$ to 
Open a File 

Figure 5-3 
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The values and meanings of action and nevfile are: 



Value Meaning 

action Specifies how the file is to be opened. This 
distinguishes between a file being open for reading, 
writing, or both reading and writing. These states 
are often identified by the mnemonics R, w, and RW 
(or wr), respectively. The keywords used when 



Keyword 


Value 


Meaning 




K$READ 


1 


Open the 
reading. 


file 


for 


K$WRIT 


2 


Open the 
writing. 


file 


for 


K$RDWR 


3 


Open the file for 
reading and writing. 


both 


K$BKUP 


7 


Open for reading 
backup facility. 


by 


K$VMR 


16 


Open for VMFA read. 





newfile 



If your program attempts to write to a file that is 
open for reading, an error code of e$unop (Unit not 
open) is returned to your program. This same error 
code is returned if your program attempts to read a 
file that is open for writing. 

Specifies what type of file should be created if the 
file does not already exist. (The file is created 
only if your program is opening the file for writing 
or for reading and writing. ) The keywords used for 
text files are: 



Keyword Value 
K$NSAM 



Meaning 

Create a new 
(SAM) file, 
the default.) 



threaded 
(This is 



K$NDAM 1024 



Create a new 
(DAM) file. 



directed 
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For SGDSOP, the newfile value is replaced by the 
new-type argument in the palling sequence. This 
argument may also include: 



Keyword 


Value 


Meaning 


K$NSGS 


2048 


Create a new SAM Segment 
Directory 


K$NSGD 


3072 


Create a new DAM Segment 
Directory 



K$NCAM 4096 . Create a new contiguous 

(CAM) file. 



KSGETCJ Specifies that PRIMOS is to use an available file 
unit, and return the selected file unit number in 
the unit parameter of the calling sequence. For 
SGDSOP, your program specifies that PRIMOS is to use 
an available file unit by supplying a unit number of 
-10000. If you want your program to specify the 
unit number instead of letting PRIMOS select the 
number, your program supplies a unit number between 
1 and 126 (or 1 and 15 for a program running under 
PRIMOS II). 



The Error Code : An output argument, code , informs your program of the 
success or failure of the operation. If code is 0, the operation was 
entirely successful. Otherwise, code is always positive. After a call 
to SRSFXS, SGDSOP, or SRCH$$ to open a file, code may have one of many 
values. Volume of this series contains a comprehensive list of all 
standard file system error codes. Error codes specific to this 
operation are: 



Keyword Value Meaning 

ESFIUS 5 File in use. The file being opened is 

already open on another file unit, or by 
another user. Normally, a file that is 
open for reading cannot be opened for 
writing, nor can a file open for writing be 
opened for reading. A file that is open 
for writing can have only one file unit 
open to it, whereas a file open for reading 
can have many file units open to it. 
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Keyword Value Meaning 

If you expect your program to open a file 
that may occasionally be in use by another 
process for a short period of time, 
consider having your program repeatedly 
attempt to open an in-use file for 30 
seconds or a minute, sleeping one second in 
between each attempt by calling SLEEPS. 

See Chapter 8, FILE ATTRIBUTES, for more 
information on the read/write lock. 

E$DKFL 9 The disk is full. This error can occur 

only if a new file is being created, and 
hence cannot occur if the action portion of 
the key argument is kSread . 

E$NRIT 10 Insufficient access rights. If the file 

being opened already exists, this means 
that the user running your program does not 
have sufficient access rights to the file. 
If the file does not exist, then the user 
does not have Add rights to the directory 
in which the file is to be created. 

For calls to SRSFXS, this error code may 
indicate a problem attaching to the 
directory that was specified by the 
pathname argument of the calling sequence. 
In this case, the user does not have Use 
access to at least one directory in the 
pathname. 

E$FNTF 15 Not found. The file being opened does not 

exist. The action portion of the key 
argument is probably k$read ; otherwise, 
the file would be created. 

For calls to SRSFXI, this error code may 
indicate a problem attaching to the 
directory that was specified by the 
pathname argument of the calling sequence. 
In this case, at least one directory in the 
pathname does not exist. Even if the 
action portion of the key argument is 
k$writ or kSrdwr , no directory is ever 
created via a call to SRSFX$. You must use 
the DIR$CR subroutine to create a 
directory. 
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Keyword Valve Meaning 

E$ITRE 57 Illegal treename. (SRSFX$ only.) This 

indicates that the pathname supplied to 
SRSFX$ does not conform to the syntax rules 
for a pathname. See the Prime User's Guide 
for a description of the syntax of a 
pathname. 

E$MXQB 143 Maximum quota exceeded. This error can 

occur only if a new file is being created, 
and hence cannot occur if the action 
portion of the key argument is k$read . 

E$IACL 150 Entry is an access category. The specified 

file system object is an access category. 
See Chapter 7, ACCESS CONTROL LISTS (ACLS), 
for information on access categories. 

E$NINF 159 No information. This indicates that some 

error occurred, but the user running your 
program does not have List access to the 
directory involving the error. In such a 
case, the e$ninf error code is always 
returned to prevent the user or calling 
program from getting any information about 
the directory. Therefore, this error code 
indicates any possible error, in addition 
to a simple case of insufficient access. 



The File Type : The returned file type is valid when the returned error 
code is 0. It is not valid in any other case. 

The file type is one of the following five values: 



Value 



A SAM file has been 
PRWF$$, and similar 



Meaning 

opened. Use RDLIN$, WTLINS, 
subroutines to read or write it. 



A DAM file has been opened. Use RDLIN$, WTLIN$, 
PRWF$$, and similar subroutines to read or write it. 

A SAM segment directory (SEGSAM) has been opened. Use 
SGDR$$ to operate on members of this segment 
directory. See Chapter 6, DATA STORAGE AND RETRIEVAL, 
for information on how to do this. 

A DAM segment directory (SEGDAM) has been opened. Use 
SGER$$ to operate on members of this segment 
directory. See Chapter 6, DATA STORAGE AND RETRIEVAL, 
for information on how to do this. 
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Value Meaning 

4 A top-level directory has teen opened. Use DIR$SE, 
DIR$RD, ENT$RD, and RDEN$$ to read information on 
files in this directory. See Chapter 6, DATA STORAGE 
AND RETRIEVAL, for information on how to do this. 

7 A GAM file has been opened. Use RDLIN$, WTLIN$, 
PRWF$$, and similar subroutines to read or write it. 



Examples : The following example shows how a FCRTRAN program would open 
the file MYFILE in the current directory for reading: 

CALL SRGH$$(K$READ+K$GETU, 'MYFILE' ,6, UNIT, TYPE, CODE) 
IF (0ODE.NE.0) GO TO 1000 



1000 GALL ERRFR$(K$IRTN,CODE, 'MYFILE' ,6, 'MYPRCGRAM' ,9) 
RETURN 



The next example illustrates the use of the newfile value in the key 
argument of the calling sequence to SRCH$$. The file ANOTHER_FILE is 
opened for rea din g and writing in the current directory. If it does 
not exist, it will be created as a DAM (directed) type file. Only the 
subroutine call itself is shown; the error code would be examined in 
the same fashion as shown in the example above. 

CALL SRCH$ $ (K$RDWR+K$NDAM+K$GETU , ' ANGTHER_FILE ' , 12 , UNIT , 
& TYPE, CODE) 



Positioning a File to Bnd-of-file 

When your program is writing data to a text file, you may want it to 
add new data to the end of the existing file and leave the previously 
entered data intact. To position a newly opened file to the 
end-of-file location, have your program call a subroutine named POSIT, 
shown below, with the HALF INT file unit number of the file, and a HALF 
INT returned error code. Your program then checks the returned error 
code to make certain the operation succeeded. If it did not, your 
program closes the opened file, produces an error message, and aborts. 
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The following FORTRAN statements illustrate the procedure. 

CAUL SRCH$$(K$WRIT+K$GETa, 'MYFUE' ,6, UNIT, TYPE, CODE) 

IF (CODE.NE.O) GO TO 1000 
C 

CALL POSIT(UNrr,CODE) /* Position to end of file. 

IF (CODE.NE.O) GO 1!0 1001 
C 

1000 CALL ERRPR$(K$IRTN,0CO:,'MYFILE\6 ( 'MyPR0GRAM',9) 
RETURN 

C 

1001 CALL SP^$$(K$aX6,0,0,UNrT,TYPE,I) /* Don't overwrite CODE! 
GO TO 1000 



The POSIT subroutine mainly uses a form of the PRWF$$ subroutine that 
positions a file. Figure 5^1 illustrates the calling sequence of the 
PRWF$$ subroutine to position toward end-of-file. 

The POSIT subroutine might be written as follows: 

SUBROUTINE POSIT(UNIT,00DE) 
INTEGER*2 UNTT.aODE 
C 

C This subroutine positions the specified file unit to the 
C end-of-file location. It returns the success or failure 
C of the operation in the CODE parameter. 
C 

$INSERT SYS00M>ERRD.INS.FTN 
$INSERT SYSOOM>KEYS.INS.FTN 
C 

INTBGER*2 RNW 
C 

10 CALL PRWF$$(K$POSN+K$PRER, /* Position relative. 
& UNIT, /* Pass the file unit number. 
& I£C(0), /* This pointer is unused during a 
& /* position-only operation. 
& 0, /* Another unused value in this case. 
& 2147483647, /* Largest positive INTEGER*4 number. 
& RNW, /* Unused, but may be overwritten anyway. 
& OODE) /* The error code. 
C 

C CODE should never be 0. If it is, it means the file is 
C very large. Loop until we reach the end of the file. 
C 

IF (CODE.EQ.O) GO TO 10 /* File is very big! 
C 

C However, if the returned error code is E$EOF (End of file), 
C then we succeeded, so set it to 0. In any case, return. 
C 

IF (CCDE.EQ.E$EOF) CODE=0 /* Success. 

RETURN 

END 
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Truncating a File 

Before closing a file you have written to, it is good practice to have 
your program truncate the file. This tells FRIMOS to make the current 
position of the file the new end-of-file location. 

If your program just created the file, this operation is not necessary. 
However, if your program has opened an existing file and overwritten 
it, your program may not have written up to the current end-of-file 
location of the file. If this is the case, and your program performs 
no truncation, the file ends up having more data than was intended, and 
the chances are good that one record of the old file data has been 
partially overwritten by the new data. 

The truncation operation is simple, and is always done by FRWF$$. 
Figure 5-5 illustrates the calling sequence of the PRWF$$ subroutine to 
truncate a file. A sample use of FRWF$$ follows: 

CALL FRW$$(K$TRNC, /* Truncate the file. 
& UNIT, /* The file unit number. 
& LOC(O), /* Ignored when truncating. 
& 0, /* Ignored when truncating. 
& 000000, /* Truncate at the current position. 
& RNW, /* Ignored when truncating, but play it safe. 
& CODE) /* The error code. 
C 

IF (OQDE.NE.O) CALL ERRPR$(K$IRTN,CODE, /* Not fatal. 
& 'Cannot truncate file' ,20, 'MYPROC&AM' ,9) 

As shown in the example above, most programs do not regard an inability 
to truncate a text file as an error, although they do produce an error 
message. For example, the PRIMOS editor ED treats an inability to 
truncate a file as a nonfatal error. This is because the data have 
been written, but there exists the possibility of extraneous data in 
the file. 

Volume of this series contains a comprehensive list of all standard 
file system error codes. Error codes that may typically be returned as 
a result of attempting to truncate a file follow. 
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Position Toward End-of-file 



File Unit 
Number 



K$POSN + K$PRER n 



NULL() in PL/I or 
LOC(O) in FORTRAN 

— (Zero) 



t t 

HALF HALF 
INT INT 



t 
PTR 



f 
HALF 

INT 



2147483647 
(231-1) 



t 
FULL 

INT 



i I I i I 

PRWF$$ (key, unit, ignored 1, ignored 2, far_forward, overwritten, code) 

I i 



HALF HALF 
INT INT 



Standard 
- Error 
Code 



_^ Ignore 
Value 



Calling Sequence of PRWF$$ to 
Position Toward End-of-file 

Figure 5^4 
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Keyword Value Meaning 

E$EOP 1 End of file. This can occur only if the 

call to PRWF$$ inadvertently specifies that 
the position of the file be changed. The 
fifth argument in the call to PRWF$$ should 
always he an INTEGER*4 zero (000000 in 
FORTRAN, OL in FMA). If it is not, this 
error code may he returned. 

E$B0F 2 Beginning of file. This can occur only if 

the call to PRWF$$ inadvertently specifies 
that the position of the file he changed. 
The fifth argument in the call to PRWF$$ 
should always be an INTEGER*4 zero (000000 
in FORTRAN, OL in FMA). If it is not, this 
error code may be returned. 

E$UNOP 3 Unit not open. The specified file unit is 

not open, oris open only for reading. 

This usually indicates a program error, 
although it can also be the result of the 
user exiting the program via 00NTROL-P, 
typing CLOSE ALL, and then typing START. 

E$FIUS 5 File in use. The file being truncated is 

already open on another file unit, or being 
used by another user. This error code 
usually indicates that the open file has a 
read/write lock setting of UFDT or NONE, 
because the program has the file open for 
writing, and yet at least one other file 
unit is open to the file for reading or 
writing. 

Chapter 8, FILE ATTRIBUTES, contains 
information on the read/write lock. 
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Truncate File at Current Position 



File Unit 
Number 



K$TRNC 



1 I , 



HALF HALF 
INT INT 



PTR 



NULL ( ) in PL/I or 
LOC(O) in FORTRAN 



(Zero) 



(Zero), to Truncate 
at Current Position 



HALF 
INT 



FULL 
INT 



III I I 

PRWF$$ (key, unit, ignored_1, ignored_2, ignored_3, overwritten, code) 

I I 



HALF HALF 
INT INT 



Standard 
■ Error 
Code 



Ignore 
Value 



Calling Sequence of FRWF$$ to 
Truncate a File 

Figure 5-5 



Second Edition 



5-20 



TEXT STORAGE AND RETRIEVAL 



dosing a File 

It is very easy to close a file. The best method is to close the file 
by unit number. This means that only the file unit specified in the 
call to CL9$FU is closed. Figure 5-6 illustrates the calling sequence 
of the CLO$FU subroutine. 

A sample use of CLO$FU is: 



CALL CLO$FU(UNIT,CODE) 

IF (OOnE.NE.O) CALL ERRPR$(K$IRTN, CODE, 'Cannot close' ,12, 
& 'MYFRCGRAM',9) 



If a nonzero error code is returned, your program should treat it as a 
fatal error, because subsequent operations on the file by the same 
program, other programs, or the user may fail. In addition, a failure 
to close may indicate a program error or a disk error, both of which 
suggest that the program should not attempt to continue processing. 

Your program may also close a file by name by using the CLO$FN 
subroutine by passing the same pathname that was used to open the file. 
Figure 5-7 illustrates the calling sequence of the CLO$FN subroutine. 

When a file is closed by name, all file units opened to the file by the 
user are closed. This function is rarely needed, because most programs 
open a file on only one file unit at a time. However, interactive 
users often find this ability useful, such as when they try to write 
out an edited command input file, and receive a "File in use" message 
from the editor. At that point, a CLOSE filename command fixes the 
problem, no matter what the file unit number for filename is, as long 
as no other users have the file open. 

Here is a sample use of closing a file by name: 

call clo$fn( 'Mmm>MYFILE ' , code) ; 

if code"=0 then call errpr$(k$irtn,code, 'Cannot close ',12, 

'MYPROGRAM',9); 
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Close a File Unit Number 



File Unit 
Number ' 



HALF 
INT 



CLO$FU (unit, code) 



HALF 
INT 



Standard 
- Error 
Code 



Calling Sequenoe of CLO$FU 
Figure 5-6 
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Close One or More File Units by Pathname 



Pathname of 
Target Object 



< =188 
STRING 



CLO$FN (name, code) 

I 



HALF 
INT 



Standard 
-*- Error 
Code 



Side Effects: May reset current attach point. 



Calling Sequence of CLO$FN 
Figure 5-7 
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HOW TO READ AND WRITE VARIABLE-LENGTH TEXT FILES 

Use the RDLTN$ subroutine to read a variable-length, record file 
(compressed or uncompressed), and use the WTLTNS subroutine to write a 
variable-length record file (compressed). 



Note 

In most cases, variable-length record files are compressed. In 
other words, contiguous spaces in a line are compressed into a 
two-byte code to save disk space. Therefore, this section will 
describe only the reading and writing of compressed files. For 
information on the format of compressed variable-length record 
files, see the section entitled FORMAT OF A VARIABLE-LENGTH 
RECORD FILE , later in this chapter. 



This section describes: 

• The RDLTN$ and WTLIN$ interfaces 

• Sample uses of RDLIN$ and WTLDT$ 

The RDLTN$ and WTLIN$ Interfaces 

The subroutine interfaces for RDLIN$ and WTLTN$ are identical. Each 
subroutine has the following arguments: 

• A file unit 

• A character buffer 

• The length of the buffer (in halfwords) 

• An error code 

For RDLEN$, the input arguments are the file unit and the length of the 
buffer, and the output arguments are the character buffer and the error 
code. For WTUOT$, the input arguments are the file unit, the character 
buffer, and the length of the buffer, and the only output argument is 
the error code. Figure 5-8 illustrates the calling sequence of the 
RDUN$ subroutine; Figure 5-9 illustrates the calling sequence of the 
WTLTN$ subroutine. 



File Unit : Each subroutine takes the file unit number as an input 
argument. The file unit must be open for rea d i ng (RDUN$), writing 
(WTLDN$), or rea di ng and writing (either subroutine). Further, the 
file that is open on the file unit must be a SAM or DAM file; it 
cannot be a segment directory or file directory. 
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The reading or writing of the line (or record) begins at the current 
position In the file for that file -unit. After the line is 
successfully read or written, the current position of the file unit 
immediately follows the line. Therefore, a subsequent call to RDUN$ 
or WTLIN$ reads or writes the next line. Your program does not need to 
call PRWF$$ to position the file to read or write successive lines of 
the file. 



Input or Output Line : The input or output line is a CHARACTER(*) 
ALIGNED variable for PL/I programs, a CHARACTER*n variable for FORTRAN 
77 programs (n must be even) , or an INTEGER*2 array for FORTRAN 66 
programs. 

When your program calls RDLIN$, RDLIN$ places the line read from the 
file into input_line , assuming a successful invocation of RDLIN$ has 
occurred. The input line is padded with trailing spaces if the actual 
line is shorter than the size indicated by max_line_length . If it is 
longer than max_line_length , the line is truncated on the right. When 
your program calls WTLINS, your program passes the line that is to be 
written to the file in output_line with trailing spaces up to the end 
of output_line (as represented by max_line_length ) . FL/I automatically 
appends the necessary trailing spaces when the variable is set, whereas 
FORTRAN programmers must ensure trailing spaces are used to pad the 
string. If no trailing spaces are present, the length of the line that 
is written to the file is the max_line_length . 

Maximum Line Length : Your program passes the length of the input or 
output line in halfwords to RDLIN$ and WTLINS. Therefore, if the input 
or output line is a GHARACTER(80) ALIGNED variable, max_line_length is 
always 40, because one halfword contains two bytes. If the character 
buffer is an INTEGER*2 array dimensioned to 40, then, again, the length 
of the buffer is 40, because one INTEGER*2 element is a halfword. 

RDLIN$ and WTLIN$ never reference the input or output line beyond the 
boundary specified by max__line_length . They both use max_line_length 
as the maximum possible length of the line, and always consider the 
current (or operational) length of the line in characters to be 
max_line_length times two, minus the number of trailing spaces. 
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Read a Line of Text 



File Unit 
Number 



HALF 
INT 



Maximum Length of 
■ input_line 
(halfwords) 



HALF 
INT 



RDLINS (unit, input_line, max_line_length, code) 



STRING 



Line Input From ^_ 
File, Blank-padded 



HALF 
INT 



Standard 
-*- Error 
Code 



Calling Sequence of RDLINS 
Figure 5-8 
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Write a Line of Text 



File Unit 
Number " 



T 
HALF 

INT 



Line to be Output 
to File, Blank-padded 



Maximum Length of 

output-line 

(halfwords) 



STRING- 



HALF 
INT 



L1MT I 

WTLIN$ (unit, output-line, max-line-length, code) 

I 



HALF 
INT 



Standard 
-*- Error 
Code 



Calling Sequence for WIUJH$ 
Figure 5-9 
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The Error Code : An output argument, code , informs your program of the 
success or failure of the operation. If oode is 0, the operation was 
entirely successful. Otherwise, code is always positive. After a call 
to RDLIN$ or WTLTNS, oode may have one of many values. Volume of 
this series contains a comprehensive list of all standard, file system 
error codes. Error codes specific to this operation are: 



Keyword Value Meaning 

E$EOF 1 End of file (RDLIN$ only) . The end of the 

file was reached. The contents of the 
character buffer are undefined. Normally, 
this means that there is no more data in 
the file, but it could mean that there is 
an incomplete line at the end of the file, 
that is, data without a following new-line 
character (ASCII 212). 

E$UN0P 2 Unit not open. When calling RDLIN$, this 

means the file unit is open only for 
writing, or is not open at all. When 
calling WTLIN$, this means the file unit is 
open only for reading, or is not open. 

E$BPAR 6 Bad parameter. The length of the buffer as 

passed by the calling program is a negative 
number. 

E$DKFL 9 The disk is full (WTUN$ only). The line 

could not be completely written to the file 
because the disk was full. The amount of 
data successfully written to the file is 
undefined, so the only way to recover from 
this error is to call PRWF$$ to read the 
file position before calling WTLINS, and 
reposition the file after the e$dkfl error 
occurs before trying to write the line 
again or truncating the file. 

E$MXQB 143 Maximum quota exceeded (WTLIN$ only). The 

line could not be completely written to the 
file because the quota for the directory 
was exceeded. The amount of data 
successfully written to the file is 
undefined. The only way to recover from 
this error is to call PRWF$$ to read the 
file position before calling WTLTN$. Then, 
before trying to write the line again or 
truncating the file, reposition the file 
after the e$mxqb error occurs. 
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Sample Programs Using RDLIN$ and WTLIN$ 

Here is a sample FORTRAN subroutine that uses WTLIN$ to write lines to 
an open file unit. If a disk-full or quota-exceeded error occurs, the 
user is given an opportunity to delete files and restart the program, 
and the subroutine retries the write in the correct fashion. This 
subroutine has the same calling sequence as WTLIN$. 

SUBROUTINE WRITE(UNIT, BUFFER, BUFLEN.CCDE) 
INTEGER*2 UNIT, BUFFER(l),BUFLEN, CODE 

C 

C BUFFER can be dimensioned to just 1, even though it is probably 

C larger, because this subroutine does not reference its contents; 

C it simply passes the buffer on to WTLIN$. 

C 

SINSERT SYSCOM>ERRD.INS.FTN 

$INSERT SYSCOM>KEYS.INS.FTN 

C 

INTEGER*2 RNW,PATHNM(40),PATHLN,00OE2 
INTEGER*4 POSITN /* A fullword variable. 
C 

C First use PRWF$$ to determine our current position in the file. 
C 

GALL PRW$$(K$RPOS, /* Special "read-position" function. 

& UNIT, /* The file unit. 

& LOC(O), /* Unused during a read-position. 

& 0, /* Also unused during a read-position. 

& POSITN, /* Report position in POSITN. 

& RNW, /* Unused, but always play it safe. 

& CODE) /* The error code. 
IF (CODE.NE.O) RETURN /* Failure. 
C 

C Now that we know the position of the file before the attempt to 
C write the line, we attempt to write the line. 

C 

1 CALL ¥TLIN$ (UNIT, BUFFER, BUFLEN, CODE) /* Simple enough. 

C 

C Examine the return code. If disk-full or quota-exceeded, do 

C special processing. Otherwise, return. 

C 

IF (CODE. NE.E$DKFL. AND. CODE. NE.E$MXQB) RETURN 
C 

C A disk-full or maximum-quota error has occurred. We want to tell 
C the user to clean up the directory and type START. First, output 
C the error message, along with the full pathname of the file being 
C written (so the user knows where to delete files!). 



C 



CALL GPATH$(K$UNIT,UNIT,PATHNM,80,PATHLN,CODE2) /* Get the 
& /* full pathname of the file open on the file unit. 
IF (CCDE2.EQ.0) GO TO 10 /* Error? 
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C 

C If we can't get the treename, ignore the error, but make the 

C error message useful. 

C 

CALL ERRPR$(K$IRTN,CODE, 'Unknown file name' ,17, 
& 'WRITE ',5) 
GO TO 20 
C 

C Otherwise, produce an error message showing the treename. 
C 

10 CALL ERRPR$(K$IRTN,CODE,PATHNM,PATHLN, 'WRITE' ,5) 
C 

C Now explain to the user what must be done. 
C 
20 CALL TNOU(O.O) /* Blank line. 

CALL TNOUA('Pree up some space using DELETE, then type ' , 
& 43) 
CALL TN0U( 'START to continue. ' , 19) 
CALL TNOU(O.O) 
C 

C Now invoke a new command level, and hope we return. 
C 

CALL COMLV$ 
C 

C User has typed START, reposition the file, and retry the write. 
C 

CALL PRWF$$(K$FOSN+K$PREA, /* Position absolute. 
& UNIT, /* Hopefully this is still open! 
& LOC(O), /* Unused during a position. 
& 0, /* Also unused. 

& POSITN, /* Specify the desired position. 
& RNW, /* Unused, but play it safe. 
& CODE) /* The error code. 
C 

C If it works, retry, else return to the caller. 
C 

IF (O0DE.EQ.0) GO TO 1 
RETURN 
C 

END 
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The following is a sample use of RDLIN$. This P L/I subroutine serves 
as an interlude for RDLINS. It returns a GHARACIER(80) VARYING string 
containing the input line. 

read: proc(unit, line, code); /* Similar to RDLIN$, but no buffer 

length, and LINE is a varying 
character string. */ 
del unit fixed bin(15), /* The file unit (input). */ 
line char(80) var, /* The line read (output). */ 
code fixed bin(15), /* The error code (output). */ 
buff char(80); /* This is what is passed to RTTT.TNS. */ 

call rdlin$ (unit, buff ,40, code); /.* 40 halfwords = 80 chars. */ 
if code=0 then LLne=triin(buff , '01 'b); /* Store line without 

trailing spaces. */ 
else line-' ' ; /* If error, do clean up the line. */ 
end; /* read: proc */ 



HOW TO READ, WRITE, AND POSITION FIXED-LENGTH FILES 

You use the PRWF$$ subroutine to read, write, and position fixed-length 
record files. This section: 

• Describes the PRWF$$ interface 

• Shows some sample uses of PRWF$$ 



The PRWF$$ Interface 

PRWF$$ is a multipurpose subroutine; its interface is complex. This 
section describes the primary functions of PRWF$$ for manipulating 
files containing fixed-size records of data. 

The following table shows which figures illustrate the calling sequence 
of PRWF$$ for each PRWF$$ function described in this section: 



Figure 


Function 


5-10 


Reading a File 


5-11 


Writing a File 


5-12 


Positioning a File 


5-13 


Reading the Position of a File 


5-5 


Truncating a File 



This section describes the arguments common to reading, writing, 
positioning, truncating, and reading the position of a file. 
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Read a File 



File Unit . 
Number 



KSREAD 



1 



HALF 



Pointer to 
Data Buffer 



Number of Halfwords 
to Read (Unsigned) 



r 



(Zero), to Read 
at Current Position 



PTR 



HALF 
INT INT , 
t t 1 

PRWF$$ (key, unit, addr (buffer) 



HALF FULL 

INT INT 

* ♦ 

size, rel-posn, halfwords-read, code) 



HALF 
INT 
ARRAY'" 



I I 



....jrHALF 
INT 



HALF 
INT 



Buffer to Which 
Data Are Transferred 



Standara 

Error 

Code 



Number of 
- Halfwords 
Actually Read 



Side Effects: Contents of buffer elements halfwords-read +1 through size are 

undefined after the operation if fewer halfwords than requested were read. 



Calling Sequence of PRWF$$ to 
Read a File 

Figure 5-10 
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Pointer to 
Data Buffer" 



File Unit 
Number ' 



K$WRIT 1 

HALF 

INT 

t 



HALF 
INT 



Buffer From Which 
Data Are Transferred 



t 

PTR 



HALF 

INT 

ARRAY 
\ 



♦ 



Number of Halfwords 
to Write (Unsigned) 



r 



(Zero), to Write 
at Current Position 



\HALF FULL 
INT INT 



PRWF$$ (key, unit, addr (buffer), size, rel-posn, halfwords-written, code) 



HALF 
INT 



HALF 
INT 



Standard 

Error 

Code 



Number of 
Halfwords 
Actually Written 



Calling Sequence of FRWF$$ to 
Write a File 

Figure 5-11 
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Position a File 



File Unit 
Number 



K$POSN + K$PREA 



1 



HALF HALF 



NULL ( ) in PL/I or 
LOC(O) in FORTRAN 



(Zero) 



Desired File 
Position 



PTR 



HALF FULL 

INT INT " "" INT INT 

♦ I ♦ ♦ ♦ 

PRWF$$ (key, unit, ignored-1, ignored-2, position, overwritten, code) 

HALF HALF 
INT INT 



Standard 

Error 

Code 



Ignore 
Value 



Calling Sequence of FRWF$$ to 
Position a File 

Figure 5-12 
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File Unit. 
Number 



K$RPOS 



i l„ r 



NULL ( ) in PL/I or 
LOC(O) in FORTRAN 



(Zero) 



HALF HALF 


' HALF 








INT INT P f w INT 

III 1 

PRWF$$ (key, unit, ignored-1, ignored-2, position, 

I 


overwritten, code) 

1 1 


FULL 


HALF HALF 


11 


T 


IM 


r T INT 

Standard 
1 — +- Error 
Code 




Current File^ 

Position 






Ignore 

Value 



Calling Sequence of PRWF$$ to 
Read the Position of a File 

Figure 5-13 
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Key : The key argument tells PRWF$$ what operation is to be performed: 

Key Meaning 

K$READ Read data from the file starting at the 
current position. 

K$WRIT Write data to the file starting at the current 
position. 

K$POSN+K$PREA Position the file to the specified location. 

K$TRNG Truncate the file at the current position. 

K$RPOS Return the current position of the file. 

The above functions represent all of the functions you need to make 
full use of PRWF$$ for text files. There are more key values you can 
pass, but aside from two special functions, these involve performing 
two or more of the above operations at one time. Generally, you should 
avoid the use of such combined operations, because ambiguity can result 
if you perform combined operations and a nonzero error code is 
returned. For example, if you attempt to pre-position the file and 
read data at the same time, it is unclear what has actually happened if 
the returned error code is e$eof . 



File Unit : The file unit must be open for reading, writing, or both 
reading and writing. Further, the file that is open must be a SAM or 
DAM file. It cannot be a segment directory or file directory. 

The data are read or written beginning at the current position in the 
file for that file unit. After the data are successfully read or 
written, the current position of the file unit is changed to 
immediately follow the data. Therefore, a subsequent call to PRWF$$ 
reads or writes subsequent data; you do not need to call PRWF$$ to 
position the file when reading or writing contiguous data in file. 

Pointer to a Buffer : You supply a pointer to the buffer as an input 
argument to PRWF$$, whereas the buffer itself is used as input or 
output data by PRWF$$, or not used at all, depending on the function 
you are requesting. This argument is used only during calls to read or 
write data; in all other cases, LOC(O) or INTL(O) may be specified in 
FORTRAN 66 or FORTRAN 77, and NULL () may be specified in PL/I. 

When your program performs a read or write operation, the buffer may 
have any appropriate declaration as long as it begins and ends on a 
halfword boundary and resides within a single segment. Unless you 
explicitly instruct them to do so, Prime linkers do not put appropri- 
ately declared buffers into memory in such a way that the buffers cross 
segment boundaries. 
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For example, a FORTRAN programmer may choose to use an INTEGER*2 array 
as the buffer. A PL/I programmer might find using a structure useful. 
Because PRWF$$ is the "raw data mover" for the PRIMOS file system, the 
data may be of any size and shape. 

However, your program must also supply the length of the buffer in 
halfwords in the next argument. 

Length of the Buffer : The length of the buffer is an unsigned number 
that represents the number of halfwords in the buffer. If it is 0, 
then no data is transferred to or from the buffer by PRWF$$. 



Note 

The maximum value of the size argument is 65,535 because it is 
an unsigned HALF INT argument. If you wish to read or write an 
entire segment, you cannot do so in one PRWF$$ operation, 
because 65,536 halfwords are in an entire segment. Instead, 
use two separate calls to PRWF$$, specifying a size of 32,768 
in each call. 



File Positioning Information : Your program uses a FULL INT argument to 
communicate with the PRWF$$ subroutine concerning the file position. 
Its use depends on the function being performed. 

When reading or writing data, this argument's value should always be 
in PL/I, and 000000 or INTL(O) in FORTRAN. If it is nonzero, PRWF$$ 
first positions the file forward or backward relative to the current 
position based on the value of this argument (positive or negative) . 
It is recommended that you avoid this functionality, as it is intended 
only for applications that perform many positioning operations. 

When positioning the file, the value of this argument should be the 
desired position in the file. File position is measured in halfwords. 
The first halfword of the file is position 0, the second is position 1, 
the third is position 2, and so on. 

Number of Halfwords Actually Read or Written : PRWF$$ returns the 
number of halfwords actually read or written during a read or write 
operation to your program. The value of this argument is not modified 
for other PRWF$$ operations, but it is recommended that a variable 
always be passed. 

Normally, a read or write operation completes successfully, in which 
case PRWF$$ sets this argument to the same value supplied as the length 
of the buffer. However, if an error such as end-of-file or disk-full 
occurs, the number of halfwords actually transferred may range from 
to the length of the buffer. 
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Therefore, unless the returned error code is 0, this value should 
always be checked to see how many halfwords were actually transferred. 



The Error Code : An output argument, code , informs your program of the 
success or failure of the operation. If code is 0, the operation was 
entirely successful. Otherwise, code is always positive. After a call 
to FRWF$$ to read or write data, code may have one of many values. 
Volume of this series contains a comprehensive list of all standard 
file system error codes. Codes specific to this operation follow. 



Keyword Value 
E$EOF 1 



Meaning 

End of file. The end of the file was 
reached. If no data were to be 
transferred, this error code indicates that 
an attempt was made to position the file 
past the end-of-file position. The file is 
positioned at end-of-file when this error 
occurs. 

If data were to be read from a file, this 
error code indicates that the end of the 
file was reached during the process. 
However, some data may or may not have 
actually been read into the buffer. The 
number of halfwords actually read will be 
returned in the argument described above. 
This value ranges from to one less than 
the length of the buffer when the e$eof 
error code is returned. The contents of 
the buffer following the last halfword 
transferred (as indicated by the number of 
halfwords actually read) are undefined. 

Unless the file is being simultaneously 
written by another process or on another 
file unit, any further attempts to read the 
file without first repositioning it result 
in e$eof being returned with the number of 
halfwords transferred set to 0. 



E$B0F 



If data were to be written to the file, 
this error code indicates that an attempt 
to position the file failed. This means 
that the value of the file position (a 
doubleword value) was not 0. 

Beginning of file. The beginning of the 
file was reached. This should occur only 
if an attempt is made to position the file 
backward, using relative positioning keys. 
If the key value is one of the values 
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Keyword Value 



Meaning 

described above, then this error means that 
the value of the file position is negative 
instead of as it should be. 



E$UNOP 



E$DKFL 



9 



Unit not open. If the key specified a read 
operation, then the file unit is open only 
for writing or is not open at all. If the 
key specified a write operation, then the 
file unit is open only for reading or is 
not open at all. If any other operation 
was specified, then the file unit is not 
open. 

The disk is full. This occurs only during 
a write operation. The buffer could not be 
completely written to disk because the disk 
was full, so anywhere from halfwords to 
one less than the length of the buffer 
halfwords were written. 



After the data are written by ERWF$$, the 
file is automatically returned to its 
pre-write position. Therefore, your 
program can easily retry the operation by 
simply calling PRWF$$ in the same manner 
after freeing up disk space in some 
fashion. 

ESMXQB 143 Maximum quota exceeded. This occurs only 

during a write operation. The buffer could 
not be completely written to disk because 
the quota on the directory was exceeded; 
therefore, anywhere from halfwords to one 
halfword less than the length of the buffer 
were written. 

After the data are written by PRWF$$, the 
file is automatically returned to its 
pre-write position. Therefore, your 
program can easily retry the operation by 
simply calling PRWF$$ in the same manner 
after freeing up some directory space or 
increasing the directory's quota. 



Sample Uses of PRWF$$ 

Here is a sample FORTRAN subroutine that uses PRWF$$ to write records 
to an open file unit. If a disk-full or quota-exceeded error occurs, 
the user is given an opportunity to delete files and restart the 
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program, and the subroutine will retry the write in the correct 
fashion. This subroutine has the same calling sequence as PRWF$$. 

SUBROUTINE mWFCKEY.UNIT.LOCBUF.BUFLM.POSN.R^.OODE) 

INTEGER*2 KEY, UNIT .BUFLEN.RNW, CODE 

INTEGER*4 IOCBUF.POSN 
C 

$INSERT SYSCOM>ERRD.INS.FTN 
$INSERT SYSCOM>KEYS.INS.FTN 
C 

INTEGER*2 RNW,PATHNM(40) ,PATHLN,0QDE2 
C 

1 CALL PRW$$(KEY,UNIT,IOCBUF,BUFI^N,PC>SN,PvNW,CDDE) 

2 IF (CODE. NE.E$DKFL. AND. CODE. NE.E$MXQB) RETURN 
C 

C Disk-full or quota-exceeded. Tell the user to clean up the 
C directory and type START. First, output the error message, 
C along with the full pathname of the file being written (so 
C the user knows where to delete files ! ) . 
C 

CALL GPATH$(K$UNIT,UMT,PATHNM,80,PATHLN,CODE2) /* Get the 
& /* full pathname of the file open on the file unit. 

IF (CODE2.EQ.0) GO TO 10 /* Error? 
C 

C If we can't get the treename, ignore the error, but make the 
C error message useful. 
C 

CALL ERRPRSCKSIRTN.CODE, 'Unknown file name' ,17, 
& 'PRVF',4) 

GO TO 20 
C 

C Otherwise, produce an error message showing the treename. 
C 

10 CALL EPJlPR$(K$IRTN,aKE,PATHNM,PATHLN, 'PRWF' ,4) 
C 

C Now explain to the user what must be done. 
C 
20 CALL TNOU(O.O) /* Blank line. 

CALL TNOUA('Free up some space using DELETE, then type ' , 
& 43) 

CALL TNOU( 'START to continue. ' ,19) 

CALL TNOU(0,0) 
C 

C Now invoke a new command level, and hope we return. 
C 

CALL CQMLV$ 
C 

C User has typed START, so retry the write. 
C 

IF (AND(KEY,K$POSR).NE.O) GO TO 1 /* Retry exactly as 
& /* specified if post -positioning desired. 
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GALL I^WSSCKEY.UNIT.KlCBUF.BUELEN.fXXXXJO.RNW.OCDE) 

GO TO 2 /* Otherwise, retry with no positioning because 

& /* the positioning portion of the operation has already 

& /* happened. 

END 



The next example shows a subroutine that simulates a RDLIN$ interface 
for a fixed-length record file. The record length is determined by the 
size of the RDLTN$ buffer being passed. The calling program calls this 
subroutine just as it would call RDLIN$, except that the file is a 
fixed-length record file, in which each record has trailing spaces. A 
similar subroutine could be written that simulates a WTLIN$ interface 
for fixed-length record files. 

SUBROUTINE RTTT.TN(UNIT, BUFFER, BUFLEN, CODE) 
INTEGER*2 UNIT,BUFFER(1), BUFLEN, CODE 

C 

C BUFFER can be dimensioned to just 1, even though it is probably 

C larger, because this subroutine does not reference its contents; 

C it simply passes the buffer on to WTLIN$. 

C 

$INSERT SYSCOM>ERRD.INS.FTN 

$INSERT SYS0OM>KEYS.INS.FTN 

C 

INTEGER*2 RNW, CODE, I, START 
C 

CALL PRWF$$(K$READ, /* Read a record. 
& UNIT, /* The file unit. 
& LCC(BUFFER), /* The buffer. 
& BUFLEN, /* The length of the buffer. 
& 000000, /* No positioning. 

& ENW, /* The number of halfwords actually read/written. 
& CODE) /* The error code. 
IF (CODE. El?. 0) RETURN /* Success. 
C 

C If an error occurred, we must first fill the buffer with spaces, 
C starting with the word following the last word successfully 
C read. 
C 

C If the error code was not end-of-file, however, pretend that no 
C halfwords were read at all. 
C 

IF (CODE.NE.E$EOF) RNW=0 /* No words read. 
C 

IF (RNW.EQ. BUFLEN) GO TO 20 /* Unlikely that the buffer was 
& /* completely filled. 
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START=RNW+1 /* Start with the next halfword. 

DO 10 I=START,BUFLEN 
BUFFER(I)=' ' 
10 CONTINUE 
C 

C Now, if at least one halfword was read, then return an error 
C code of zero. This can happen only on an end-of-file error. 
C 
20 IF (RNW.NE.O) 0CDE=0 

RETURN 
C 

END 



The next sample subroutine shows how to position a fixed-length record 
file to a particular record number. This subroutine is called with the 
file unit to be positioned, the desired position in terms of a record 
number, and the record length (in halfwords) for the file. It returns 
a standard file system error code. 



SUBROUTINE POS(UNIT,REQ«D,RECILEN,OODE) 
INTEGER*2 UNIT , RECLEN , CODE 
INTEGER*4 RECNO 
C 

$ INSERT SYSCOM>ERRD.INS.FTN 
$ INSERT SYSCOM>KEYS.INS.FTN 
C 

INTEGER*2 RNW 
C 

CALL PRWF$$(K$POSN+K$PREA, /* Position absolute. 
& UNIT, /* The file unit. 

& IOC(O), /* Unused during a position-only operation. 
& 0, /* Also unused. 

& REGNO* INTL(REGLEN) , /* The file position. 
& RNW, /* Unused, but play it safe. 
& CODE) /* The error code. 
C 

RETURN 
END 



FORMAT OF A VARIABLE-LENGTH RECORD FILE 

Variable-length record text files have the following attributes: 

• Each line of text can contain from characters to as many as 
needed. 

• Each line of text begins on a halfword boundary. 

• Each character in a line of text occupies one 8-bit byte. 
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• A new-line character (ASCII line-feed, 212 octal), and 
optionally a pad character (000 octal or 240 octal) follows each 
line of text to cause each new line to begin on a halfword 
boundary. 

• Space compression is performed by substituting two or more 
spaces with an ASCII DC1 character (221 octal) followed by a 
byte representing the number of spaces. 

• In general, the last line of a file is terminated by a new-line 
character and an optional pad character, the same as all other 
lines in the file. When an unterminated last line is 
encountered, the behavior of Prime and user-written software is 
undefined. Most programs ignore all text following the last 
new-line code. Some programs, however, treat the end of the 
file as an implicit new-line character, and therefore recognize 
an unterminated last line as if it were terminated. 

For example, suppose that a file named REBEL contains the following 
lines of text: 



Rebel, Jean-Fery Position: Composer Born: 1661 Died: 174? 
Interests: Swimming, Hiking, Dissonance 



"When stored using the standard PRIMOS variable-record organization, the 
disk copy of this file would be: 



R 


e 


b 


e 1 , 


J 


e 


a 


n 


- F e r 


y DC1 04 P 





s 


i 


t 


i 





n : C 





m 


P 





s e r DC1 


04 B o r 


n 


: 




1 


6 


6 


1 DC1 04 D 


i 


e 


d 


: 


17 4 


7 LF NUL I 


n 


t 


e 


r 
£ 


e 


s 


t s : 

Diss 


S 




w 

n 


i 
a 


m 

n 


m i n g 
c e LF 


H i 


k 


i 


n 



In the above example, DC1 represents the ASCII DC1 code (221 octal), 
and 04 represents the number of spaces. The new-line character is 
represented by LF (212 octal), and NUL indicates a null character (000 
octal). 

Notice that the final character in the file is a new-line code (LF). 
It is not followed by a NUL code because the LF code is in the 
low-order byte of the 16-bit halfword. A NUL code is inserted when it 
follows an LF code only if the LF code is in the high-order byte of a 
16-bit halfword in a disk record. Some programs use the space 
character (240 octal) as the fill character instead of NUL. 
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Caution 

A program that searches forward or backward in a file for 
particular characters (such as new-line) must take into account 
the space compression character DC1 (221 octal). If a 
character is preceded by an odd number of DC1 characters in the 
file, the character is to be interpreted as a space count. 

Another concern is that some programs may generate multiple 
consecutive DC1 and space count characters, which must be 
treated collectively as the appropriate number of spaces. 

Finally, it is possible for some programs to output a DC1 
followed by a byte containing or 1 . These values are to be 
taken literally, that is, no spaces (the DC1 code is a 
"no-op"), or one space. Do not interpret a space count of as 
266 decimal or 65536 decimal (byte-overflow and 
halfword-overf low values, respectively). 



FORMAT OF A FIXED-LENGTH RECORD FILE 

Fixed-length record text files have the following attributes: 



• A record length must be defined for the file. This record 
length should be expressed in terms of the number of bytes per 



record. If this record length is odd, 
the file (explained below) must be 
records in the file must also be 
utilities that support fixed-length 
only even-length records. 



the blocking factor for 

even, and the number of 

even. However, ERIMOS 

records in files support 



• A blocking factor should be defined for each program that reads 
or writes the file. The blocking factor is a number that 
specifies how many records are read and written during a single 
read/write operation. 



• Each line of text is always r characters in length, where 
the record length for the file. 



r is 



If a line that is less than r characters long is to be written 
to the file, spaces (240 octalT are appended to the line by the 
user program before writing the record. This leaves the line 
left- justified in the record. 

If a line that is more than r characters long is to be written 
to the file, the line is truncated to r characters, and the 
remaining information on the line is discarded by the user 
program. 
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• Each, line is implicitly terminated by the end of the record, 
that is, after the rth character in the record. The last 
character of record n of a file is immediately followed by the 
first character of record n+1 . The new-line character, ASCII LF 
(212 octal), has no special meaning in fixed-length record 
files. 

• No space compression is performed. The variable-record space 
compression character, ASCII DC1 (221 octal), has no special 
meaning in fixed-length record files. 

• The last record is immediately followed by the end of the file. 
Therefore, no data follows the last record of the file. If an 
attempt is made to read past the last record in a file, PRIMOS 
returns an error code. 

It is possible that a partial record (less than r characters 
long) follows the last complete record in a file. This often 
indicates that the file is corrupted. When such a partial 
record exists, the data should be ignored, and an error message 
should be generated to inform the user of the program that a 
possible data file corruption has occurred. 

To ensure that no partial records are inadvertently created, 
programs that write a fixed-record length file should always 
truncate the file immediately after writing the last record. 

PRIMOS does not maintain information on the record length for the file. 
All programs that use the file must know the record length. Similarly, 
PRIMOS does not maintain any history of blocking factors that were used 
when the file was written. 

In fact, PRIMOS performs its own record blocking, optimized for the 
type of disk being used. A PRIMOS block is referred to as a record by 
other Prime documentation, or as a PRIMOS , disk , or physical record 
when clarification is needed. Usually, PRIMOS stores 2048 bytes per 
record, plus some housekeeping information. This housekeeping 
information is used by PRIMOS to provide optimized record blocking in a 
fashion that is transparent to user programs. 



Determining the Blocking Factor 

The choice of the appropriate blocking factor for your program depends 
upon the needs of the program. The only rule imposed by PRIMOS is that 
the blocking factor must be even if the record length is odd; PRIMOS 
allows only reading, writing, positioning, and truncating of files at 
halfword boundaries. 
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Aside from that rule, the determination of a blocking factor is fairly 
straightforward. In general, the larger the blocking factor, the fewer 
read/ write operations needed to peruse a large file. However, a larger 
blocking factor increases the amount of time needed to perform most 
individual read/write operations, and also requires more program memory 
to hold the records. Because PRIMOS provides large amounts of virtual 
memory, large blocking factors are preferred. 

Although ERIMOS does not require a consistent blocking factor to be 
used when reading and writing the file, it is good practice to use the 
same blocking factor throughout any given program. Once the file is 
written, other programs using different blocking factors can read the 
same file. However, they must use the same record length, or the data 
will be misinterpreted. 



Calculating Record Position During Random-access Operations 

The position of a record in a fixed-length record file is calculated as 
follows : 



n = the record number (starting at record 0) 

r = the record length in characters 

p = the position of the record in characters (starting 

at character in the file) 
p = n * r 

If r is odd, p will be odd whenever n is odd. In such a case, the file 
should be positioned to record number n-1, and the record copied 
starting at the appropriate low-order byte of the halfword in which 
record n begins. 

Assuming p is even, the halfword position of the record is p divided by 
2. The number of halfwords to read in is calculated as follows: 

r = the record length 

b = the blocking factor (r * b is even) 

h = the number of halfwords to read 

h = (r * b) / 2 
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QUESTIONS AND ANSWERS ABOUT TEXT FILES 

This section answers some typical questions about text storage and 
retrieval. 



• How can I open only an existing file for writing, or reading and 
writing; that is, without creating a new file if it doesn't exist? 

Answer : There are several ways to do this. The most straightforward 
way is to test for the existence of the file before opening it. This 
is done by calling the SRSFX$ or SRCH$$ subroutines with a key_ value of 
k$exst . For files within segment directories, use the SGD$EX 
subroutine . 

There is a drawback to this method, however; another user might delete 
the file between your call to test for its existence and the call to 
open the file. 

A more reliable way to open an existing file is to first open it for 
reading. If the file does not exist, an error code e$fntf is returned. 
If the file does exist, it is opened for reading, preventing any other 
users from deleting it. 

At this point, call the CH$M0D subroutine with the file unit number and 
a ke^ argument of k$writ or k$rdwr . This changes the state of the file 
unit from read to write or read/write. If an error code such as e$fius 
(File in use) is returned, close the unit and return the error code. 

A sample PL/ 1 subroutine that opens a file for writing, without 
creating the file, follows. 

open_existing_file: proc(filename) returns(fixed bin(15)); 

/* Declarations are not shown except for the input argument and 
the returned value. */ 

del filename char(*) var, 
code fixed bin(15); 

call srsfx$ (k$read+k$getu , filename , unit , type , , " , basename , 

suf f ix_used, code) ; 
if code~=0 then return(code) ; 

call ch$mod(k$writ, unit, code); 

if code~=0 then call clo$fu(unit , ignore_code) ; 

return(code) ; 

end; /* open_existing_f ile : proc */ 
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• How do I choose between SRSFX$, SGD$OP, SRGH$$, and others? 

Answer : If you want to open a file that may or may not have one or 
more suffixes appended to its name, use SRSFX$. If you are programming 
in PL/I or Pascal, and you want to open a file by using a pathname 
(such as MYDIR>THIS_FILE) , use SRSFX$. 

If you want to open a file that is not a pathname, and is in the 
current directory, use SRCH$$ for maximum performance. 

If you want to open a file that is in a segment directory that you have 
already opened on another file unit, use SGD$OP. 

If you want to close a file by name, use CLO$FN. If you want to close 
a file by unit number, use CLO$FU. 

If you want to test for the existence of a file within a segment 
directory, use SGD$EX. If you want to test for the existence of a file 
within a file directory, make the decision as to which subroutine to 
use (SRSFX$ or SRCH$$) as if you were opening the file, and use the 
k$exst key. 

If you want to delete a file, use FIL$DL if it is a member of a 
directory, or SGD$DL if it is a member of a segment directory. 

If you want to change the access of an open file unit, always use 
CH$MOD. 

If you want to open a member of an open segment directory, use SGD$OP. 

• What is the k$getu additive key for? What if I don't use it? 

Answer : Add the k$getu key to k$read , k$writ , and k$rdwr when you open 
files using the SRSFX$ or SRCH$$ subroutines. This causes an available 
file unit to be selected by PRIMOS and returned in the unit argument of 
the calling sequence. 

If you do not specify k$getu when opening a file, PRIMOS treats the 
unit argument as an input-only argument , and uses the number in unit as 
the - file unit number. This is not recommended practice. 

Dynamic unit allocation has been preferred since PRIMOS Revision 16, 
when the k$getu functionality was first made available. Only programs 
that have to maintain past behavior for compatibility reasons should 
pass file units to PRIMOS when opening files. All other programs 
should use k$getu or specify -10000 as the unit number, whichever is 
needed by the procedure called. 
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If you decide not to use k$getu , be aware that there are two additional 
error codes that may be returned. The e$uius (Unit in use) code is 
returned if the file unit you specified is already open. The e$bunt 
(Bad unit number) code is returned if the file unit you specified Is 
not a legal file unit number. However, the error code e$fuiu (All file 
units in use) is not returned, because you are not asking PRIMOS to 
allocate a new file unit. 
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Data Storage and 
Retrieval 



Certain applications require the ability to maintain one or more data 
bases on disk. Prime provides several facilities for building and 
manipulating data bases from within programs and via interactive 
sessions. These include MIDASPIUS, DBMS, DISCOVER, DIFORMATION, and 
PRISAM. Information on these products can be found in the Prime 50 
Series Technical Summary . 

In addition, PRIMOS provides several facilities to allow applications 
to perform their own data base management. These facilities are: 

• The PRIMOS file system, which allows the hierarchical 
organization of files, identified by name or by number. 

• The semaphore mechanism, which provides a method of handling 
concurrency problems that occur when several users attempt to 
access the same data base simultaneously. 

• The Prime 50 series architecture, which facilitates rapid access 
by permitting the sharing of memory-resident data among several 

users. 

This chapter describes the PRIMOS file system as used by data base 
management software. Volumes II and III of the Subroutines Reference 
Guide describe the use of semaphores and shared memory for data base 
management purposes. In addition, the Prime 50 Series Technical 
Summary and the System Architecture Reference Guide describe semaphores 
and shared memory in detail. 
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FILE ORGANIZATION 

Two useful file organizations provided by the ERIMOS file system are: 

• Segment directories, for organizing data files by number 

• File directories, for organizing data files by name 

This chapter describes how to manipulate segment directories and file 
directories under PRIMOS. This is followed by a short discussion on 
the reading and writing of data files (whether in segment directories 
or file directories). Finally, a question and answer section is 
provided. 

SEGMENT DIRECTORIES 

Your program manipulates files within a segment directory by first 
opening the segment directory itself and then positioning the segment 
directory to the desired file by using SGDR$$ . Your program then calls 
SGDSOP, SGD$EX, or SGD$DL with the file unit number of the open segment 
directory to manipulate members of the segment directory. When your 
program is finished with the segment directory, it closes the segment 
directory unit by calling CLO$FU. 

Once a file within a segment directory is opened, you can treat it as a 
text file (described in Chapter 5, TEXT STORAGE AND RETRIEVAL) or a 
data file (described later in this chapter). The remainder of this 
section describes: 

• Subroutines used to access segment directories 

• How to open a segment directory 

• How to position a segment directory 

• How to extend a segment directory 

• How to open a file within a segment directory 

• How to delete a file within a segment directory 

• How to scan a segment directory 



Subroutines Used to Access Segment Directories 

The subroutines most often used when accessing segment directories 
follow. 
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Subroutine Use 

SRSFX$ Accepts a pathname and calls SRGH$$ to manipulate 
the object according to the specified key. 
SRSFX$ calls SGDR$$ to position to a file. 

SGDR$$ Positions an open segment directory to a 
specified member. Positioning is necessary 
before calling SRCH$$ or SGD$DL to operate on a 
member of a segment directory. In addition, 
SGDR$$ is used to expand and truncate segment 
directories, and to read the position of an open 
segment directory. 

SGD$OP Opens a member file of an open segment directory, 
optionally Creating the member if it does not 
already exist. 

SGD$DL Deletes a member file of an open segment 
directory. 

SGD$EX Tests for the existence of a member file of an 
open segment directory. 



How to Open a Segment Directory 

Your program must open a segment directory before it can access members 
of the segment directory. Use the SRSFX$ or SRCH$$ subroutine to open 
the segment directory. Your program must open the segment directory 
for reading and writing if it is going to create or delete members. If 
your program is going to open and close only existing members, it need 
open the segment directory only for reading. Opening a segment 
directory only for writing (but not reading) is not recommended. 

When your program calls the SRSFX$ or SRCH$$ subroutine to open a 
segment directory, it provides: 

• The name of the segment directory to be opened 

• A key that specifies how the segment directory is to be opened 

The SRSFX$ or SRGH$$ subroutine attempts to open the specified segment 
directory, and returns to your program: 

• An error code that indicates whether the operation was 
successful 

• A file unit number that identifies the open segment directory. 
Your program uses this number when performing operations (such 
as extend and truncate) on an open segment directory or when it 
manipulates members of a segment directory. 
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• The file type, indicating the type of segment directory just 
opened (including SEGSAM and SBGDAM) 

Youx program should close a segment directory when finished with it. 
Do this with CLO$FU to close the file unit, as described in Chapter 5, 
TEXT STORAGE AND RETRIEVAL. 

This section describes the input and output parameters that apply when 
calling SRSFX$ and SRCH$$, and then shows a sample call to SRCH$$. 
Figure 6-1 illustrates the calling sequence of SRSFX$ to open a segment 
directory; Figure 6-2 illustrates the calling sequence of SRCH$$ to 
open a segment directory. 

The Name of the Segment Directory : The rules for specifying the 
segment directory name depend on the system subroutine being called. 
The filename may be a pathname if SRSFX$ is being used. If SRCH$$ is 
being used, the filename must be an entry name; that is, it cannot 
contain a > symbol. 

The Key : The key argument is calculated as follows: 

key = action + newfile [+ K$GETU] 
The values and meanings are: 

Value Meaning 

action Specifies whether the segment directory is to be 
opened for reading or for both reading and writing. 
These states are often identified by the mnemonics R 
and RW (or wr) , respectively. The keywords used 
when opening segment directories are: 

Keyword Value Meaning 

K$READ 1 Open the segment 

directory for reading. 

K$RDWR 3 Open the segment 

directory for both 
reading and writing. 
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Value Meaning 

When a segment directory is open for reading, and an 
attempt is made to create or delete a member of it 
or to change its size, an error code of e$unop (Unit 
not open) is returned. 

newfile Specifies what type of segment directory should be 
created if the segment directory does not already 
exist. (The segment directory is created only if it 
is being opened for writing or for reading and 
writing.) The keywords used for segment directories 
are: 



Keyword Value Meaning 

K$NSGS 2048 Create a new threaded 

(SAM) segment directory. 

K$NSGD 3072 Create a new directed 

(DAM) segment directory. 



SAM and DAM segment directories differ only in 
performance and storage efficiency, as described in 
Chapter 1, PRIMOS FILE SYSTEM CONCEPTS. 



Note 

The type of a segment directory (SAM or DAM) 
is unrelated to the type of any of its 
members. For example, a SAM segment 
directory may contain DAM files. 



K$GETU Specifies that PRIMOS is to use an available file 
unit, and return the selected file unit number in 
the unit parameter of the calling sequence. 



The Error Code : An output argument, code , informs your program of the 
success or failure of the operation. If code is 0, the operation was 
entirely successful. Otherwise, code is always positive. After a call 
to SRSFX$ or SRCH$$ to open a segment directory, code may have one of 
many values. Volume of this series contains a comprehensive list of 
all standard file system error codes. Error codes specific to this 
operation follow. 
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Open a Segment Directory, With Possible Suffix 



Pathname of 
Object to Open 



JK$READ | 
\K$RDWR j 

|k$nsgs| 
+ \k$nsgd) 

+ K$GETU 



HALF 
INT 



Number of Suffixes 
in suffixes Array 
(0 Means No Suffix 
Processing) 



Array of 

-Desired 

Suffixes 



< =128 
STRING 

I 



HALF 
INT 

\ 



>-. 



< =32 
STRING 
~~ ARRAY 



SRSFXS (key, name, unit, type, num suffixes, suffixes, basename, suffix used, code) 



I 

HALF 

INT 



1 I 

HALF HALF 

INT INT 



[ARRAY(2)] FTN/PMA 

only* 



File 
Type 



File Unit 
Number 



(1): Termination Character Position 

"(2): Length of Pathname! 
(characters) | 



- FTN/PMA only* 



I I \ 

< = 32 HALF HALF 

STRING INT INT 

^ Standard 
Error 
Code 

^ Index Into suffixes 
of Suffix Used 
(matched); Means 
Null Suffix 



*■ Final Component of name 
Without Suffix Used; Useful 
When Appending Another Suffix 



Side Effects: May reset current attach point. 

* Function value is returned in L-register; typically, you need only to declare as HALF INT, 
because first datum is all you need and is in A-register. Otherwise, you must declare it as 
FULL INT to make it work. 



Calling Sequence of SRSFX$ to 
Open a Segent Directory 



Figure 6-1 
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Open Segment Directory by Object Name 



I K$READ I 
{ K$RDWR j 

j K$NSGS | 
+ { K$NSGD j 

+ K$GETU - 



Name of 
Object 



Length of 
Object Name 
(characters) 



t 

HALF 32-^ HALF 
INT STBINGVlNT 



SRCH$$ (key, name, name_len, unit, type, code) 

1 1 1 



HALF 
INT 



HALF HALF 
INT INT 



File 
Unit 
Number 



Standard 
-*■ Error 
Code 



Object 
Type 



Calling Sequence of SRCH$$ to 
Open a Segment Directory 

Figure 6-2 
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Keyword 
E$FIUS 



Value 



E$NRIT 



10 



E$FNTF 



15 



Meaning 

File in use. The segment directory being 
opened is already open on another file 
unit, or by another user. Under normal 
look settings, a segment directory that is 
open for reading can have many file units 
open to it, but a segment directory open 
for writing can have only one file unit 
open to it. Therefore, a segment directory 
that is open for reading cannot be opened 
for writing, nor can a segment directory 
that is open for writing be opened for 
writing or for reading. 



See Chapter 8, FILE ATTRIBUTES, for 
information on the read/ write lock. 



more 



Insufficient access rights. If the segment 
directory being opened already exists, this 
means that the user does not have 
sufficient access to the segment directory. 
If the segment directory does not exist, 
then the user does not have Add access to 
the directory in which the segment 
directory is to be created. 

For calls to SRSFX$, this error code may 
indicate a problem attaching to the 
directory specified by the pathname 
argument of the calling sequence. In this 
case, the user does not have Use access to 
at least one directory in the pathname. 

Not found. The segment directory being 
opened does not exist. The action portion 
of the key argument is probably k$read , 
otherwise the segment directory would be 
created. 

For calls to SRSFX$, this error code may 
indicate a problem attaching to the 
directory specified by the pathname 
argument of the calling sequence. In this 
case, at least one directory in the 
pathname does not exist. Even if the 
action portion of the key argument is 
k$rdwr , no directory will ever be created 
via a call to SRSFX$. Use the DIR$CR 
subroutine to create a directory. 
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Keyword 
E$BNAM 



Value 



17 



E$WTPR 



56 



E$MXQB 



143 



E$NFAS 



189 



Meaning 

Illegal name. The filename or pathname as 
supplied by the calling program is not 
valid. See the Prime User's Guide for a 
description of the valid 
filename and pathname. 



syntax for a 



The disk is write-protected. A segment 
directory cannot be opened for writing, nor 
can it he created, on a write-protected 
disk. (A disk is write-protected using the 
ADDISK command, described in the System 
Operator's Guide, Volume II . ) 

Maximum quota exceeded. This error can 
occur only if a new segment directory is 
being created, and hence cannot occur if 
the action portion of the key argument is 
k$read . 

Top-level directory not found or 
inaccessible (SRSFX$ only). The first 
directory name supplied in the pathname 
could not be located on any of the system 
disks. 



The File Unit Number : The returned file unit number is valid only when 
the returned error code is 0. After opening a segment directory, your 
program passes the returned file unit number to other system 
subroutines (such as SGDR$$ and SGD$OP) to manipulate the segment 
directory and its members. 

Once your program closes the segment directory, the file unit number is 
returned to the free pool for reuse by PRIMOS when another file is 
opened. 



The File Type : The returned file type is valid only when the returned 
error code is 0, and the segment directory is actually opened. The 
file type is one of the following five values: 



Value Meaning 

A SAM file has been opened. Use RDLIN$, WTLIN$, 
PRWF$$, and similar subroutines to read or write it. 
(See Chapter 5, TEXT STORAGE AND RETRIEVAL, for 
information on how to do this.) 

1 A DAM file has been opened. Use RDT.TNS , WTLIN$, 
PRWF$$, and similar subroutines to read or write it. 
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Value Meaning 

(See Chapter 5, TEXT STORAGE AND RETRIEVAL, for 
information on how to do this.) 

2 A SAM segment directory (SEGSAM) has been opened. Use 
SGDR$$ to operate on members of this segment 
directory. 

3 A DAM segment directory (SEGDAM) has been opened. Use 
SGDR$$ to operate on members of this segment 
directory. 

4 A top-level directory has been opened. Use DIR$LS, 
DIR$RD, ENT$RD, to read information on files in this 
directory. (See the section entitled FILE 
DIRECTORIES , later in this chapter, for information on 
how to do this.) 



Note 

It is important to understand that opening a segment directory 
is very different from opening a segment directory member. The 
above section describes how to open a segment directory. 
Information on opening members of a segment directory is in an 
ensuing section entitled How to Open a File Within a Segment 
Directory . 

Example : The following example shows how a FORTRAN program would open 
the object MYSEGDIR in the current directory for reading and writing, 
creating a SAM segment directory if it does not already exist: 

CALL SRCH$$(K$RDWR+K$NSGS+K$GETU, 'MYSEGDIR' ,8, UNIT, TYPE, CODE) 
IF (CODE.NE.O) GO TO 1000 



1000 CALL ERRFR$(K$IRTN,CODE, 'MYSEGDIR' ,8, 'MYPROGRAM' ,9) 
RETURN 



How to Position a Segment Directory 

Before opening a file within a segment directory, your program must 
position the segment directory to the appropriate member file. You 
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position a segment directory by using the SGDR$$ subroutine. When your 
program calls SGDR$$ to position a segment directory, it provides: 

• The file unit of the open segment directory 

• A kej that specifies that a position operation is to be 
performed 

• The desired position of the segment directory, also known as the 
member file number 

The SGDR$$ subroutine attempts to position the specified segment 
directory, and returns to your program: 

• An error code indicating whether the operation was successful 

• A file existence indicator. This integer indicates whether the 
specified position indicates an existing file, a nonexistent 
file, or lies beyond the limits of the segment directory 

This section describes the input and output parameters that apply when 
calling SGDR$$ to position a segment directory, and then shows a sample 
call to SGDR$$. Figure 6-3 illustrates the calling sequence of SGDR$$ 
to open a segment directory. 

The Desired Position of the Segment Directory : Your program passes the 
desired position of the segment directory, which ranges from to 65535 
(-1 signed), inclusive. The resulting position in the segment 
directory may or may not have a member file present. 

The Error Code : An output argument, code , informs your program of the 
success or failure of the operation. If code is 0, the operation was 
entirely successful. Otherwise, code is always positive. After a call 
to SGDR$$ to position a segment directory, code may have one of many 
values. Volume of this series contains a comprehensive list of all 
standard file system error codes. Error codes specific to this 
operation are: 

Keyword Value Meaning 

E$EOF 1 End of file. The desired position is 

beyond the end of the segment directory. 
The segment directory is left positioned at 
the end of the directory. If a call to 
SRCH$$ with a key argument of k$writ or 
k$rdwr is performed within the segment 
directory at this point, a new file is 
created and the segment directory is 
automatically extended by one file entry. 
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Keyword Value Meaning 

E$UNOP 3 Unit not open. The specified file unit is 

not open. This usually indicates a program 
error, although it can also be the result 
of the user exiting the program via 
OQNTROL-P, typing CLOSE ALL, and then 
starting the program again by typing START. 



The File Existence Indicator : If the positioning operation is 
successfully performed, SGDR$$ returns a file existence indicator 
( result ) to your program. This variable takes on one of the following 
values: 



Value Meaning 

1 The specified position is within the bounds of the 
segment directory, and a member file exists at this 
position. In other words, a member file exists with 
this member file number. 

The specified position is within the bounds of the 
segment directory, but no member file exists at this 
position. In other words, no file exists with this 
member file number. 

-1 The specified position is at the end of the segment 
directory. Therefore, no member file exists at this 
position. If a new member file is created at this 
position, the segment directory is automatically 
extended to accommodate it; however, the file number 
of the newly created member file is not necessarily 
position , but is instead the end-of-file member number 
plus one (which may be less than or equal to 
position ) . 



Example : The following sample use of SGER$$ positions the segment 
directory open on file unit SGUNIT to member file number 5. If the 
file exists, it prints the word EXISTS. If the file does not exist, it 
prints the words NOT THERE. If the position is at the end of the 
segment directory, it prints the words AT END OF SEGDIR. 
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Position Segment Directory to Entry Number 



Unit Number 

of Segment 

Directory 



K$SPOS 



Desired Position 
"(Member File Number) 



t t * 

HALF HALF HALF 
INT INT INT 

\ I 1 

SGDR$$ (key, unit, position, 



result, code) 

\ \ 

HALF HALF 
INT INT 



Standard 

Error 

Code 



1 : position Contains a File 
0: position Contains No File 
- 1 : position Is Beyond End of 
Segment Directory 



Calling Sequence of SGDR$$ to 
Position a Segment Directory 

Figure 6-3 
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CALL SGmSSCKSSPOS.SGUNIT.S.INDICB.OODE) 

IF (OODE.NE.O) GO TO 1000 

IF (INDIC8) 10, 20, 30 
C 
10 CALL TNOU( 'AT END OF SEGDIR' , 16) 

GO TO 100 
20 CALL TNOUC NOT THERE ',9) 

GO TO 100 
30 CALL TNOUC EXISTS ',6) 

GO TO 100 
C 
100 



1000 CALL ERRFR$(K$IRTN,CODE, 'SGDR$$ error' , 12, 'MYFROGRAM' ,9) 
RETURN 



How to Extend a Segment Directory 

To create a new member file within a segment directory when the member 
file number represents a position beyond the end of the segment 
directory (as indicated by a returned error code of e$eof when trying 
to position the segment directory to the specified file number), your 
program must extend the segment directory to accommodate the new 
member. 

When a segment directory is extended, FRIMOS adds new placeholders for 
segment directory members. These placeholders represent nonexistent 
files: they may be used by your program to hold new files. You use the 
SGDR$$ subroutine to extend a segment directory. When your program 
calls SGDR$$ to extend a segment directory, it provides: 

• The file unit of the open segment directory. 

• A key that specifies that an extend operation is to be performed 

• The desired size of the segment directory, also known as the new 
end-of -segment-directory location 

This section describes the input and output parameters that apply when 
calling SGDR$$ to extend a segment directory, and then shows a sample 
call to SGDR$$. Figure 6-4 illustrates the calling sequence of SGDR$$ 
to extend a segment directory. 
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The Desired Size of the Segment Directory : Your program passes the 
desired size of the segment directory ( new_size ), which, ranges from 
to 65535 (-1 signed), inclusive. 



Note 

You cannot use k$msiz to extend a segment directory to a full 
length of 65,536 member entries, because the data type of the 
desired size cannot accommodate the number 65536. If it is 
necessary to extend a segment directory to 65,536 entries, 
first extend it to 65,535 entries using SGDR$$, which leaves 
the segment directory unit positioned at the end of the segment 
directory; then use SGD$OP to create a member file, which, 
when at the end of a segment directory, automatically extends 
the segment directory by one entry; use CLO$FU to close the 
newly created (and empty) member file; finally, use SGD$DL to 
delete the member file, leaving an empty entry at member file 
number 65535. 

Keep in mind that a segment directory of size position can have 
member file numbers ranging from through position- 1 . For 
example, extending a segment directory to 65 entries for member 
file numbers ranging from through 64, but not including 
member file number 65. 



The Error Code : An output argument, code , informs your program of the 
success or failure of the operation. If code is 0, the operation was 
entirely successful. Otherwise, code is always positive. After a call 
to SGDR$$ to extend a segment directory, code may have one of many 
values. Volume of this series contains a comprehensive list of all 
standard file system error codes. Error codes specific to this 
operation are: 



Keyword Value Meaning 

E$UNOP 3 Unit not open. The specified file unit is 

open only for reading, or is not open. 
This usually indicates a program error, 
although it can also be the result of the 
user exiting the program via OONTROL-P, 
typing CLOSE ALL, and then typing START. 

E$DKFL 9 The disk is full. The segment directory 

may or may not have been extended, but it 
has not been extended to the desired size. 
The segment directory is left positioned at 
the end of the directory. 
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Extend (or Truncate) Segment Directory 



Unit Number 
of Segment - 
Directory 



K$MSIZ 



Desired Size 
(Number of 
Possible Members) 



(Zero) 



t t t t 

HALF HALF HALF HALF 
INT INT INT INT 

III I 

SGDR$$ (key, unit, new size, ignored, code) 



HALF 
INT 



Standard 
• Error 
Code 



Side Effects: Position of unit after operation is at end of segment 
directory if code is 0, undefined otherwise. 



Calling Sequence of SGDR$$ to 
Extend a Segment Directory 

Figure 6-4 
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Keyword Value Meaning 

E$MXQB 143 Maximum quota exceeded. The segment 

directory may or may not have been 
extended, but it has not been extended to 
the desired size. The segment directory is 
left positioned at the end of the 
directory. 

Example : The following sample use of SGDR$$ extends the segment 
directory open on file unit SGONIT to hold 205 entries. 

GALL SGDR$$(K$MSIZ,SGONrr, 205 .IGNCRE, CODE) 
IF (OCDE.NE.O) GO TO 1000 



C 

1000 GALL ERRPR$(K$IRTN,CODE, 'SGDR$$ error' ,12, 'MYPRCGRAM' ,9) 
RETURN 



How to Open a File Within a Segment Directory 

Before data in a file are accessed, the file must be opened . To open a 
file within a segment directory, have your program position the segment 
directory by using the SGDR$$ subroutine, and then open the member file 
by using the SGD$OP subroutine. When your program calls the SGD$OP 
subroutine, it provides three items of information. 

• The file unit number of the open segment directory that is 
positioned to the member file to be opened 

• A key_ that specifies how the member file is to be opened 

• The file unit number on which the member file is to be opened 

The SGD$OP subroutine attempts to open the specified file and returns 
to your program: 

• An error code indicating whether the operation was successful 

• A file unit number that identifies the open file. This number 
is used when performing operations (such as read and write) on 
an open file. 

• The file type, indicating the type of file just opened 
(including SAM, DAM, GAM, SEGSAM, and SEGDAM). 
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Tills section describes the input and output parameters used when 
calling SGD$OP, and then shows a sample call to SGD$OP. Figure 6-5 
illustrates the calling sequence of SGD$OP. 



The Key : The key argument = action. Its values and meanings are: 



Value Meaning 

action Specifies how the file is to be opened. This 
distinguishes between a file being open for reading, 
writing, and both reading and writing. These states 
are often identified by the mnemonics R, W, and RW 
(or wr), respectively. The keywords used for 
opening files are: 



Keyword 


Value 


Meaning 




K$READ 


1 


Open a file for 
only. 


reading 


K$WRIT 


2 


Open a file for 
only. 


writing 



K$RDWR 3 Open a file for readljig 

and writing. 

K$VMR 16 Open a file for VMFA 

read, used only before 
calling one of the EPF 
subroutines to initial- 
ize or execute the file. 



If your program attempts to write to a file that is 
open for reading, an error code of e$unop (Unit not 
open) is returned to your program. This same error 
code is returned if your program attempts to read a 
file that is open for writing. 



The Desired Unit Number : Your program passes the value -10000 to 
indicate that PRIMOS is to choose an available file unit number. If 
you want your program to specify the unit number instead of letting 
PRIMOS select the number, your program supplies a unit number between 1 
and 126 (or 1 and 15 for a program running under PRIMOS II). SGD$OP 
returns the chosen file unit number used as the value of the SGD$OP 
function. 
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Open Member of Segment Directory 



Unit Number 
of Segment 
Directory 



K$READ 
K$WRIT 
K$RDWR| 
K$VMR 



-10000 
(Find Available 
Unit Number) 
1<n<126 
(Use this Unit 
Number) 



HALF HALF 
INT INT 



HALF 
INT 



HALF 
INT 



Type of Newly Created File: 

K$NSAM 
K$NDAM 
K$NSGS 
K$NSGD 
K$NCAM 



\ \ \ i 

SGD$OP (key, seg-unit, file-unit, type, new-type, code) 

1 I I 



HALF 
INT 



HALF 
INT 



HALF 
INT 



Unit Number 
Member Opened On 



Standard 

Error 

Code 



Type of File Opened 



Value 


1 
2 
3 

7 



Type 

SAM File 

DAM File 

SAM Segdir 

DAM Segdir 

CAM File 



Side Effects: If seg-unit is at end of segment directory and key is K$WRIT or 
K$RDWR, SGD$OP attempts to automatically extend segment 
directory by one entry, which also repositions seg-unit to new 
end-of-segdir position; otherwise, size of segment directory 
and position of seg-unit remain unchanged. 



Calling Sequence of SGD$OP 
Figure 6-5 
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The Error Code : An output argument, code , informs your program of the 
success or failure of the operation. ~ If code is 0, the operation was 
entirely successful. Otherwise, code is always positive. After a call 
to SGD$OP to open a segment directory member, code may have one of many 
values. Volume of this series contains a comprehensive list of all 
standard file system error codes. Error codes specific to this 
operation are: 



Keyword Value Meaning 

E$FIUS 5 File in use. The file being opened is 

already open on another file unit, or is 
being used by another user. Normally, a 
file that is open for reading cannot be 
opened for writing, nor can a file open for 
writing be opened for reading. A file that 
is open for writing can have only one file 
unit open to it, whereas a file open for 
reading can have many file units open to 
it. 

If you expect your program to open a file 
that may occasionally be in use by another 
process for a short time, consider having 
your program repeatedly attempt to open an 
in-use file for 30 seconds or a minute, 
sleeping one second in between each attempt 
by calling SLEEPS. 



See Chapter 8, FILE ATTRIBUTES, for 
information on the read/ write lock. 



more 



E$DKFL 9 The disk is full. This error can occur 

only if a new file is being created, and 
hence cannot occur if the action portion of 
the key argument is k$read . 

E$NRIT 10 Insufficient access rights. If the file 

being opened already exists, this means 
that the user does not have sufficient 
access to the parent segment directory. If 
the file does not exist, then the user does 
not have Write access to the parent segment 
directory in which the file is to be 
created. 

E$FNTS 16 Not found in segment directory. The file 

being opened does not exist in the segment 
directory. The action portion of the key 
argument is typically k$read , otherwise the 
file would have been created. 
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Keyword Value Meaning 

E$MXQB 143 Maximum quota exceeded. This error can 

occur only if a new file is being created, 
and hence cannot occur if the action 
portion of the key argument is k$read . 

E$NINF 159 No information. This indicates that some 

error occurred, but the user does not have 
List access to the directory involving the 
error. In such a case, the e$ninf error 
code is always returned to prevent the user 
or calling program from being able to 
determine any information on the directory. 
Therefore, this error code is to be 
interpreted as any possible error, in 
addition to a case of insufficient access. 



The File Unit Number : The returned file unit number is valid only when 
the returned error code is 0. After opening a file, your program 
passes the returned file unit number to other system subroutines (such 
as PRWF$$ and RDLIN$) to read, write, and position the file. 

Once your program closes the file, the corresponding file unit number 
can no longer be used. It may then be reused by FRIMOS when another 
file is opened. 

The File Type : The returned file type is valid only when the returned 
error code is 0. The file type is one of the following five values: 



Value Meaning 

A SAM file has been opened. Use RDUN$, VTLIN$, 
FRWF$$, and similar subroutines to read or write it. 
(See Chapter 5, TEXT STORAGE AND RETRIEVAL, for 
information on how to do this.) 

1 A DAM file has been opened. Use RTTT.TNS , WTLIN$, 
PRWF$$, and similar subroutines to read or write it. 
(See Chapter 5, TEXT STORAGE AND RETRIEVAL, for 
information on how to do this.) 

2 A SAM segment directory (SEGSAM) has been opened. Use 
SGDR$$ to operate on members of this segment 
directory. 

3 A DAM segment directory (SEGDAM) has been opened. Use 
SGDR$$ to operate on members of this segment 
directory. 
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Value Meaning 

7 A CAM file has been opened. Use RDT.TN$ , WTLINS, 
PRW$$, and similar subroutines to read or write it. 
(See Chapter 5, TEXT STORAGE AND RETRIEVAL, for 
information on how to do this.) 



The New File Type : Specifies what type of file should be created if 
the file does not already exist. (The file is created only if it is 
being opened for writing or for reading and writing.) The keywords 
used for text or data files are: 



Keyword 


Value 


K$NSAM 





K$NDAM 


1024 


K$NSGS 


2048 


K$NSGD 


3072 


K$NCAM 


4096 



Meaning 

Create a new threaded (SAM) file. (This is 
the default.) 

Create a new directed (DAM) file. 

Create a new threaded (SAM) segment 
directory. 

Create a new directed (DAM) segment 
directory. 

Create a new contiguous (CAM) file. 



SAM and DAM files differ only in performance and storage efficiency, as 
described in Chapter 1, PRIMOS FILE SYSTEM CONCEPTS. 

Examples : The following example shows how a FORTRAN program would open 
the file at the current position for reading in the segment directory 
open on unit SGUNIT. 



UNIT=SGD$OP(K$READ , SGUNIT , -10000 , TYPE , CODE ) 
IF (CODE.NE.O) GO TO 1000 



1000 CALL ERRPR$(K$IRTN,CODE, 'Segdir file' , 'MYPRCGRAM' ,9) 
RETURN 
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The next example illustrates the use of the new-type value in the 
calling sequence to SGD$OP. The file at the current position is opened 
for reading and writing in the segment directory open on unit SGUNIT. 
If it does not exist, it is created as a DAM (directed) type file. 
Only the subroutine call itself is shown; the error code is examined 
in the same fashion as shown in the above example. 

UNIT=SGD$OP(K$RDWR , SGUNTT , -10000 , TYPE , K$NDAM , CODE ) 



How to Delete a File Within a Segment Directory 

Your program can delete a file within a segment directory by 
positioning the segment directory with the SGDR$$ subroutine, and then 
using the SGD$DL subroutine to actually delete the file. When calling 
the SGD$DL subroutine, your program provides the file unit number of 
the open segment directory that is positioned to the file to be 
deleted. The SGD$DL subroutine attempts to delete the specified file, 
and returns an error code indicating whether the operation was 
successful. 

This section describes the input and output parameters used when 
calling SGD$E(L, and then shows a sample call to SGD$DL. Figure 6-6 
illustrates the calling sequence of SGD$DL. 

The Error Code : An output argument, code , informs your program of the 
success or failure of the operation. If code is 0, the operation was 
entirely successful. Otherwise, code is always positive. After a call 
to SGD$DL to delete a segment directory member, code may have one of 
many values. Volume of this series contains a comprehensive list of 
all standard file system error codes. Error codes specific to this 
operation follow. 



Keyword Value Meaning 

E$FDEL 11 File open on delete. The file to be 

deleted is already open on another file 
unit, or is being used by another user. 

E$FNTS 16 Not found in segment directory. The file 

being deleted does not exist in the segment 
directory, or the segment directory is 
positioned at the end of the directory. 

E$SUNO 31 Segdir unit not open. The segment 

directory unit is open only for reading, or 
is not open at all. 
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Delete Member of Segment Directory 



Unit Number 
of Segment 
Directory 



HALF 
INT 



SGD$DL (unit, code) 



HALF 
INT 



Standard 
• Error 
Code 



Calling Sequence of SGD$DL 
Figure 6-6 
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Example : The following example shows how a FORTRAN program would 
delete the file at the current position in the segment directory open 
on unit SGUNTT: 



GALL SGD$DL(SGUNIT,OCDE) 
IF (0ODE.NE.0) GO TO 1000 



1000 GALL ERRPR$(K$TRTN,OODE, 'Segdir file' , 'MYPROGRAM' ,9) 
RETURN 



How to Scan a Segment Directory 

If you want your program to scan a segment directory for all of its 
members, you use the SGDR$$ subroutine. In addition to the functions 
described earlier, this subroutine can find the file numbers of all of 
the members of a segment directory. This is referred to as the "find 
full entry" function. 

In addition, you can use the SGDR$$ subroutine to find all of the 
unused file numbers in a segment directory. This capability is useful 
when your program needs to create a new segment directory member. Your 
program can scan the segment directory for "free" member numbers, and 
use one of these numbers for the new member it is going to create. 
This capability is referred to as the "find free entry" function. 

The "find full entry" and "find free entry" functions are very similar. 
Your program provides the starting position of the segment directory, 
and SGDR$$ searches the segment directory for the first full or free 
entry starting at that position and continuing toward the end of the 
segment directory. When SGDR$$ finds the appropriate entry, it leaves 
the segment directory at that position and returns the position to your 
program. (The returned position also serves as the file number of a 
new or existing segment directory member.) 

The only difference between the two functions is that the "find full 
entry" function of SGDR$$ sets the position of the segment directory at 
the first position that corresponds to an existing member of the 
segment directory, whereas the "find free entry" function of SGDR$$ 
sets the position of the segment directory at the first position that 
corresponds to an unused member number in the segment directory. 
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When your program calls SGDR$$ to search a segment directory for a full 
or free position, it provides: 

• The file unit of the open segment directory 

• A key that specifies that a search operation is to be performed 

• The starting position of the segment directory, also known as 
the first file number to be checked 

The SGCR$$ subroutine searches the specified segment directory and 
returns to your program: 

• An error code indicating whether the operation was successful 

• The ending position of the segment directory following the 
search, also known as the first full or free entry following the 
specified starting position 

This section describes the input and output parameters that apply when 
calling SGDR$$ to search a segment directory, and then shows a sample 
call to SGDR$$. Figure 6-7 illustrates the calling sequence of SGDR$$ 
to scan a segment directory. 

The Key : Set the key argument to one of the following two values: 

Value Meaning 

KSFULL Find the first full entry 

K$FREE Find the first free entry 



The Starting Position of the Segment Directory : Your program passes 
the starting position of the segment directory, which ranges from to 
65535 (-1 signed). The resulting position in the segment directory may 
or may not have a file present. 

The Error Code : An output argument, code , informs your program of the 
success or failure of the operation. If code is 0, the operation was 
entirely successful. Otherwise, code is always positive. After a call 
to SGDR$$ to search a segment directory, code may have one of many 
values. Volume of this series contains a comprehensive list of all 
standard file system error codes. Error codes specific to this 
operation are: 
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Scan Segment Directory for Next Full/Free Entry 



Unit Number 
of Segment - 
Directory 



f K$FULL 
I KSFREE 



t t 
HALF HALF 

INT INT 



Starting Position of Scan 
(0 if First Scan, or Position 
"of Last Full/Free Entry 
Plus 1 if Not First Scan) 



HALF 
INT 



SGDR$$ (key, unit, start_position, end position, code) 



HALF HALF 

INT INT 



Standard 
■ Error 
Code 



Position of Full or Free Entry 
or - 1 if No Full/Free 
- Entry Found (Note Ambiguity: 
- 1 = 65535 unsigned, which 
is a valid member file number) 



Side Effects: The position of unit is left at end-position 

if desired entry is found; otherwise, unit is positioned 
to end of segment directory. 



Calling Sequence of SGDR$$ to 
Scan a Segment Directory 



Figure 6-7 
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Keyword Value Meaning 

E$EOF 1 End of file. The starting position is 

beyond the end of the segment directory. 
The segment directory is left positioned at 
the end of the directory. If a call to 
SRCH$$ with a key_ argument of k$writ or 
k$rdwr is performed within the segment 
directory at this point, a new member file 
is created, and the segment directory is 
automatically extended by one file entry. 

E$UNOP 3 Unit not open. The specified file unit is 

not open. This usually indicates a program 
error, although it can also be the result 
of the user exiting the program via 
CX3NTROL-P, typing CLOSE -ALL, and then 
typing START. 



The Ending Position of the Segment Directory : The SGDR$$ subroutine 
returns the ending position of the segment directory resulting from the 
search operation. If the desired entry (full or free) was found, its 
position is returned in this variable. Otherwise, a value of -1 is 
returned. 



Caution 

A returned value of -1 in this variable corresponds to an 
unsigned value of 65535, and hence is not a reliable indicator 
of a search operation that failed to find the desired entry. 
When a value of -1 is returned in this field, have your program 
call SGDR$$ to position the segment directory to file number 
65535. 

If SGDR$$ returns an end-of-file error code, or if it returns a 
file existence indicator of -1, then segment directory position 
65535 does not exist. If SGDR$$ returns a file existence 
indicator of 0, then segment directory position 65535 exists, 
but there is no file with that number (the entry is free). If 
it returns a file existence indicator of 1, then file number 
65535 exists (the entry is full). 



Example : The following sample subroutine displays a list of all full 
entries in an open segment directory by using SGDR$$ to scan for 
existing entries. 
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SUBROUTINE LISTEM(SGUN3T,CODE) 

INTEGER*2 SGUNIT.OODE 
C 

$INSERT SYSO0M>ERRD.INS.FTN 
SINSERT SYSCOM>KEYS.INS.FTN 
C 

INTEGER*2 FIIlffiR.NXTNBR.MYTH 
C 

FILNBRO 
C 
10 GALL SGm$$(K$FUIL,SOMIT,FIIlJm ( NXTNBR,G0DE) 

IF (OODE.NE.0) RETURN 
C 

IF (NXTNBR. NE.-l) GO TO 20 
C 

C The returned file number is -1, or 65535 unsigned. Find out 
C if file number 65535 is a myth. 
C 

CALL SGm$$(K$SK)S,SGUNrr,-l,MYTH,C!ODE) 

IF (00DE.NE.E$EOF) GO TO 15 
C 

CODE=0 /* Treat end-of-file as no more full entries. 

GO TO 100 
C 

15 IF (MYTH.LE.O) GO TO 100 /* No entry there. 
C 

C We have a file number in NXTNBR, print out the number with 
C an optional header. 
C 

20 IF (FILNBR.NE.O) GO TO 30 /* First full entry? 
C 

GALL TN0U( 'File numbers: ' , 13) /* Yes, explain the list. 
C 
30 GALL TNOUAC ',2) /* A little indentation. 

GALL TOVFD$ (NXTNBR) /* Number may be negative, of course. 

GALL TNOU(0,0) /* End of line. 
C 

IF (NXTNBR. EQ.-l) GO TO 100 /* Definitely last entry? 

FILNBR=NXTNBR+1 /* No, search for next entry. 

GO TO 10 /* Thanks, Debbie. . . 
C 

100 IF (FILNBR.NE.O) RETURN /* Finished with listing. 
C 

CALL TNOU( 'NO files. ' ,9) 

RETURN 
C 

END 
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FILE DIRECTORIES 

Relating primarily to the manipulation of file directories themselves, 
this section describes: 

• How to create a file directory 

• How to open a file directory 

• How to scan a file directory 

• How to determine a new filename 

The subroutines most often used when accessing file directories are: 



Subroutine 



DIR$GR 



SRSFX$ 
SRCH$$ 



DIR$RD 



ENT$RD 



Use 

Creates a directory. Your program passes the 
pathname of the directory to DIR$CR along with a 
structure defining the initial state of the 
directory. DIR$CR creates the specified 
directory. Your program may then populate the 
directory with new file system objects. 

Accepts a pathname and calls SRCH$$ to manipulate 
the directory according to the specified key. 

Accepts a filename, and searches for the 
directory in the current directory. The SRSFX$ 
subroutine calls SRCH$$ after it attaches to the 
directory specified by the supplied pathname. 
SRCH$$ can open, close, change access on, or 
verify the existence of the directory. 

Reads the next entry from an open directory, and 
returns a structure that describes the name of 
the entry and its attributes. Your program can 
use DIR$RD to read successive entries in a 
directory. 

Reads a particular entry from an open directory, 
and returns a structure that describes the name 
of the entry and its attributes. Your program 
can use ENT$RD to read the attributes of a 
particular entry in a directory by specifying the 
name of the entry. 
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How to Create a File Directory 

Your program creates file directories by using the DIR$CR subroutine. 
Your program supplies the pathname of the directory to be created along 
with control information on the type of directory to be created and on 
its attributes. Once created, the directory contains no file system 
objects; your program may then create new file system objects in the 
newly created directory. 

When your program calls the DIR$GR subroutine, it provides: 

• The pathname of the directory to be created 

• The attributes of the directory . 

The DIR$CR subroutine attempts to create the directory and returns to 
your program an error code indicating whether the operation was 
successful. 

This section describes the input and output parameters to use when 
calling DIR$CR, and then shows a sample call to DIR$CR. Figure 6-8 
illustrates the calling sequence of DIR$GR. 

The Attributes of the Directory : Your program constructs a structure 
that contains the attributes of the directory to be created, and passes 
a pointer to this structure to DIRSCR. This structure describes: 

• Whether the directory is to be the same type (ACL or password) 
as its parent, or is to be made a password directory. 

• The maximum quota of the directory. 

• The access category that is to protect the directory. 

Normally, you set the directory type to the same type as its parent; 
the maximum quota to 0, meaning no quota; and the access category to 
null, meaning default protection. 

The Error Code : An output argument, code , informs your program of the 
success or failure of the operation. If code is 0, the operation was 
entirely successful. Otherwise, code is always positive. After a call 
to DIR$CR to create a file directory, code may have one of many values. 
Volume of this series contains a comprehensive list of all standard 
file system error codes. Error codes specific to this operation 
follow. 
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Create File Directory 



Halfword 
dec 


1 



Pointer to 
Structure 



Pathname of 
Directory to ■ 
Be Created 



<=128 
STRING 

I 

DIR$CR (name, 



I 



PTR STRTJC 

1 1 

addr (attributes), code) 

1 

HALF 
INT 



20 



Version of Structure (1) 



Type of New Directory: 
K$SAME - same as parent 
K$PWD - password directory 



Maximum Quota 
(0 if no limit) 



Length of Access Category 
Name (0 if default protection) 



Access Category Name 
(not necessary if length is 0) 



Standard 
-*■ Error 
Code 



Side Effects: Resets current directory if name contains a > symbol; 
otherwise, new directory created in current directory. 



Calling Sequence of DIR$CR 
Figure 6-8 
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Keyword 

E$BPAR 

E$DKFL 
E$NRIT 



Value 
6 

9 

10 



E$ENTF 



15 



E$EXST 



18 



E$MXQB 
E$N0QD 

E$PNAC 



143 



144 



148 



E$ACNF 



155 



E$BVER 



158 



Meaning 

Bad parameter. The maximum quota for the 
directory is a negative number. 

The new directory cannot 



The disk is full, 
be created. 



Insufficient access rights. The user does 
not have sufficient access to create the 
specified directory. This error code may 
also indicate a problem in attaching to the 
directory specified by the pathname 
argument of the calling sequence. In this 
case, the user does not have Use access to 
at least one directory in the pathname. 

Not found. There is a problem in attaching 
to the directory specified by the pathname 
argument of the calling sequence. In this 
case, at least one directory in the 
pathname does not exist. 

Already exists. Another file system object 
already exists with the name of the new 
directory. The existing object may or may 
not be a file directory. 



Maxijmum quota exceeded, 
cannot be created. 



The new directory 



Not a quota disk. The disk on which the 
directory is to be created is not a quota 
disk, but the supplied structure indicates 
that a maximum quota is to be ijmposed. 

Parent not an ACL directory. The parent 
directory of the new directory is not an 
ACL directory, but the supplied structure 
indicates that the new directory is to be 
protected by an access category. 

Access category not found. The access 
category to be used to protect the newly 
created directory does not exist in the 
parent directory. 

Bad version. The version number of the 
supplied structure containing the 
attributes of the directory is not 1. The 
calling program must initialize this number 
to 1 before calling DIR$CR. 
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Keyword Value Meaning 

E$DTNS 173 Date and time not set yet. The supplied 

structure indicates that a quota is to be 
placed on the new directory, but quotas 
cannot be imposed unless the system date 
and time are set. 

ESNFAS 189 Top-level directory not found or 

inaccessible. The first directory name 
supplied in the pathname could not be 
located on any of the system disks. 

Examples: The following PL/I code illustrates a sample call to DIR$GR 
to create a new directory named FRCDO in the HDBBIT directory. The 
newly created directory will be of the same type as the HDBBIT 
directory, will be a non-quota directory, and will have no access 
category protecting it (it will be protected by the access on HDBBIT) . 

struc . version=l ; 
struc . dir_type=k$same ; 
struc . max_quota=0 ; 
struc . acc_cat= ' ' ; 

call dir$cr('HDBBIT>FRCDO\addr(struc),code); 
if code~=0 then call errpr$(k$irtn,code, 'HDBBIT>FRODO' ,12, 

'MYPROGRAM',9); 



How to Open a File Directory 

Your program must open a directory before it may read entries in the 
directory. To open the directory, your program uses the SRSFX$ or 
SRCH$$ subroutine. When calling these subroutines, your program 
provides : 

• The name of the directory to be opened 

• A key_ that specifies how the directory is to be opened 

The SRSFX$ or SRCH$$ subroutine attempts to open the specified 
directory and return to your program: 

• An error code indicating whether the operation was successful 

• A file unit number that identifies the open directory; your 
program uses this number when reading directory entries in an 
open directory 

• The file type, indicating the type of file just opened 
(including SAM, DAM, SEGSAM, SEGDAM, and Directory) 
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Additional information returned by SRSFX$ is not relevant to this 
discussion. 

This section describes the input and output parameters that apply when 
calling SRSFX$ and SRGH$$, and then shows a sample call to SRCH$$. 
Figure 6-9 illustrates the calling sequence of SRSFX$ to open a 
directory; Figure 6-10 illustrates the SRCH$$ calling sequence. 



The Error Code : An output argument, code , informs your program of the 
success or failure of the operation. If code is 0, the operation was 
entirely successful. Otherwise, code is always positive. After a call 
to SRSFX$ or SRCH$$ to open a directory, code may have one of many 
values. Volume of this series contains a comprehensive list of all 
standard file system error codes. The error code specific to this 
operation is: 



Keyword Value Meaning 

E$NRIT 10 Insufficient access rights. This means 

that the user running your program does not 
have List access to the directory. 

For calls to SRSFX$, this error code may 
indicate a problem attaching to the 
directory specified by the pathname 
argument of the calling sequence. In this 
case, the user running your program does 
not have Use access to at least one 
directory in the pathname. 

The File Type : The returned file type is valid only when the returned 
error code is and the directory is actually opened. The file type is 
one of the following five values: 

Value Meaning 

A SAM file has been opened. Use RDLIN$, Wtlin$, 
FRWF$$, and similar subroutines to read or write it. 
(See Chapter 5, TEXT STORAGE AND RETRIEVAL, for 
information on how to do this.) 

1 A DAM file has been opened. Use RDLIN$, Wtlin$, 
FRWF$$, and similar subroutines to read or write it. 
(See Chapter 5, TEXT STORAGE AND RETRIEVAL, for 
information on how to do this . ) 
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Value Meaning 

2 A SAM segment directory (SEGSAM) has been opened. Use 
SGDR$$ to operate on members of this segment 
directory. (See the section SEGMENT DIRECTORIES , 
above, for information on how to do this.l 

3 A DAM segment directory (SEGDAM) has been opened. Use 
SGDR$$ to operate on members of this segment 
directory. (See the section SEGMENT DIRECTORIES , 
above, for information on how to do this.) 

4 A top-level directory has been opened. Use DIR$LS, 
DIR$RD, ENT$RD, and RDEN$$ to read information on 
files in this directory. 

Example : The following example shows how a FORTRAN program would open 
the directory MYDIR in the current directory for reading: 

CALL SRCH$$(K$READ+K$GETU, 'MYDIR' ,5, UNIT .TYPE, CODE) 
IF (CODE.NE.O) GO TO 1000 



1000 CALL ERRPR$(K$IRTN,CODE, 'MYDIR' ,5, 'MYPRCGRAM' ,9) 
RETURN 



How to Scan a File Directory 

Once your program opens a directory, it may scan that directory. 
Scanning a directory consists of reading file system object entries. 
Your program may read entries sequentially, that is, in the order in 
which they appear in the directory, or may read particular entries by 
name. This section describes how to read a directory sequentially, one 
entry at a time, using the DIR$RD subroutine. To read sequential 
entries several entries at a time, see the description of the DIR$SE 
subroutine in Volume II of the Subroutines Reference Guide . To read 
directory entries by name, see Chapter 8, FILE ATTRIBUTES. 

After opening the directory, your program calls DIR$RD providing: 

• The file unit of the open directory 

• A key that specifies the operation to be performed 

• A pointer to a structure into which the entry information is to 
be stored 

• The size of the storage structure 
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Open a File Directory, With Possible Suffix 



Pathname of 
Object to Open 



KSREAD 
+ K$GETU- 



t t 

HALF < = 128 
INT STRING 



Number of Suffixes 
in suffixes Array 
(0 Means No Suffix 
Processing) 



Array of 

-Desired 

Suffixes 



t < =32 

HALF >_ STRING 
INT "^ ARRAY 



\ 1 



I 



I 



SRSFX$ (key, name, unit, type, num_suffixes, suffixes, basename, suffix__used, code) 



HALF 
INT 



I I 

HALF HALF 

INT INT 



\ 
< =32 
STRING 



HALF 
INT 



HALF 
INT 



[ARRAY(2)] FTN/PMA 

only* 



File 
Type 



File Unit 
Number 



(1): Termination Character Position 

"(2): Length of Pathname"] 
(characters) J 



- FTN/PMA only* 



I 



Standard 

Error 

Code 



Index Into suffixes 
_^ of Suffix Used 
(matched); Means 
Null Suffix 



Final Component of name 
W- Without Suffix Used; Useful 
When Appending Another Suffix 



Side Effects: May reset current attach point. 

* Function value is returned in L-register; typically, you need only to declare as HALF INT, 
because first datum is all you need and is in A-register. Otherwise, you must declare it as 
FULL INT to make it work. 



Calling Sequence of SRSFX$ to 
Open a File Directory 



Figure 6-9 
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Open File Directory by Object Name 



K$READ + KSGETU 



Name of Directory 



Length of Directory 
Name (characters) 



HALF 32 — •►HALF 
INT STRING INT 



SRCH$$ (key, name, name-len, unit, type, code) 

HALF HALF HALF 
INT INT INT 



File Unit^ 
Number " 



Standard 
•Error 
Code 



_^_ Object 
Type 



Calling Sequence of SRCH$$ to 
Open a File Directory 

Figure 6-10 
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The DIR$RD subroutine finds the next sequential entry in the specified 
directory and returns to your program an error code indicating whether 
the operation was successful. 

This section describes the input and output parameters to specify when 
you call DIR$RD to scan a directory, and then shows a sample call to 
DIR$RD. Figure 6-11 illustrates the calling sequence of DIR$RD. 

The Key : Your program sets the key argument to one of the following 
values: 



Value Meaning 

K$READ Read the next entry 

K$INIT Reset to the beginning of the directory 



Normally, your program passes the k$read value for key . Your program 
uses the k$init value only if the open directory is to be read again 
from the beginning, as in a two-pass directory scanning program. 



A Pointer to a Structure : Your program provides a structure that 
nm$RD fills in with information on the next entry in the directory. 
Your program passes a pointer to this structure to DIR$RD. Assuming 
DTRSRD finds an entry, it fills the structure with information such as 
the filename, the file type, and other information on the file. See 
the description of the dirjentry structure in Chapter 8, FILE 
ATTRIBUTES, for details. 



The Error Code : An output argument, code , informs your program of the 
success or failure of the operation. If code is 0, the operation was 
entirely successful. Otherwise, code is always positive. After a call 
to DIR$RD to scan a directory, code may have one of many values. 
Volume of this series contains a comprehensive list of all standard 
file system error codes. Error codes specific to this operation are: 

Keyword Value Meaning 

E$EOF 1 End of file. No more directory entries are 

present. 

E$UNOP 3 Unit not open. The specified file unit is 

not open. This usually indicates a program 
error, although it can also be the result 
of the user exiting the program via 
CONTROL-P, typing CLOSE -ALL, and then 
typing START. 
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Read Next Entry in File Directory 



File Unit 
of Directory 



K$INIT \ 
K$READ| 



t t 

HALF HALF 

INT INT 



Pointer to 
Structure 



Length of Structure 
(Currently 31) 



" 

PTR 



HALF 
INT 



t * T 

DIR$RD (key, unit, addr(dir-entry), dir-entry-len, code) 



i 1 

STRUC 



Object Name, Type, 
and Attributes 



HALF 
INT 



Standard 
Error 
Code 



(E$BFTS Implies 
Success, but More 
Info Available) 



Side Effects: Repositions unrt. 



Calling Sequence of DIR$RD 
Figure 6-11 
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Keyword Value Meaning 

E$BFTS 35 Buffer too small. The supplied structure 

is too small to hold the information. 
Unlike the other error codes, this error 
code indicates that the operation 
succeeded, but that only some of the 
available information (as much as the 
calling program has asked for) has been 
returned in the structure. 



Example : The following subroutine displays the names of all the files 
in an open file directory: 

list_file_names: proc(unit , code) ; 

del unit fixed bin(15), /* File unit directory is open on. */ 
code fixed bin(15); /* Standard f/s error code. */ 

/* Other declarations omitted. */ 

/* This subroutine assumes that the specified file unit is 
already positioned at the beginning of the directory. It 
therefore does not call DIR$RD with the K$DNIT key. */ 

first- 'l'b; 

do untiKcode'O) ; 

call dir$id.(k$read,umt,addr(dir_entry),31,code); 
if code=0 
then do; 

if first then call tnou('File names:' ,11) 
first- 'O'b; 
call tnoua(' ' ,2); 

call tnou(dir_entry . name , length( trim(dir_entry . name , 
'01 'b))); /* Don't output trailing blanks. */ 
end; /* if code=0 */ 
end; /* do until(code~=0) */ 
if code=e$eof 
then do; 

if first then call tnou('No files. ' ,9); 
code=0; 

end; /* if code=e$eof */ 
end; /* list_file_names: proc */ 
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READING AND WRITING DATA FILES 

A data file is a file containing data that does not logically break 
down into single 8-bit bytes. For example, a file that contains a list 
of employee records that contain some single-bit data is a data file, 
rather than a text file. 

In general, FRIMOS does not distinguish between text and data files. 
FRIMOS does provide a simple interface for variable-length record text 
files (the RDLIN$ and WTLIN$ subroutines) ; this interface is described 
in Chapter 5, TEXT STORAGE AND RETRIEVAL. The interface for data files 
is precisely the same interface used for fixed-length record files, 
described in Chapter 5, TEXT STORAGE AND RETRIEVAL. 

Many application programs store data files in segment directories. The 
manipulation of data files in segment directories is described in the 
section entitled SEGMENT DIRECTORIES , found earlier in this chapter. 
Whether a data file is a member of a file directory or segment 
directory, however, does not affect how it is read, written, extended, 
and truncated. These operations are very similar to the operations 
performed on fixed-length record text files. 

There are several important things to remember when you are designing a 
program that reads and writes data files: 

• There is no record length or blocking factor that PRIMOS is 
aware of. If your program writes more or less data than 
originally specified in design specification for your program, 
FRIMOS does not know to truncate or extend the data. 

• Because there is no implicit record length, your program must 
satisfy its own random-access position calculation requirements. 
FRIMOS provides the ability to position a file only to a 
specified halfword location. 

• FRIMOS allows data files to be read and written in any order. 
FRIMOS imposes no sequential ordering, although such ordering is 
typically the default. 

• The only way your program may extend the length of a data file 
is by writing new data starting at the end-of-file location; 
FRIMOS automatically extends the end-of-file location as your 
program writes the file. 

• FRIMOS allows your program to use more than one file unit at a 
time to access a single file, assuming the read/write lock 
restrictions are satisfied. You can use this capability to 
improve the performance of your program in certain cases. 

For example, suppose your program needs to read data record 
indexes at the beginning of a large file, whereas the data 
records themselves are scattered throughout the file. If your 
program uses two file units to access the file simultaneously, 
your program can position one file unit at the beginning of the 
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file to access the indexing information rapidly, and use the 
other file unit to retrieve and store the data records 
themselves. 

In most cases, data files should he created as DAM files. 



QUESTIONS AND ANSWERS ABOUT DATA FILES 

This section answers some typical questions about data storage and 
retrieval. See Chapter 5, TEXT STORAGE AND RETRIEVAL, for questions 
and answers about text storage and retrieval, including opening files. 

• Explain the relationship between SRSFXS and segment directories. 

SRSFX$ is the only file system subroutine that allows references to 
files within segment directories. A detailed description of accessing 
files within segment directories is provided earlier in this chapter. 

SRSFX$ is a high-level interface for opening a segment directory 
member. You typically use SRSFX$ for opening one or two particular 
members of a segment directory, because it provides a simpler interface 
than the more complex method recommended in this chapter. 

• Aren't there more subroutines I can use to do things like change 
filenames and numbers, and determine pathnames? 

Yes, there are. Most application programs do not need to use these 
subroutines during most of their development process. However, 
functions such as changing the number (position) of a segment directory 
member are sometimes useful when you construct administrative tools for 
the application. Determining the full pathname of a file system object 
is also useful. 

For information on changing filenames and numbers, see the descriptions 
of the SGDR$$ and CNAM$$ subroutines in Volume II of the Subroutines 
Reference Guide . Similarly, the GPATH$ subroutine is useful for 
deteiroining the pathname of an open file system object or an attach 
point. In fact, one of the examples in Chapter 5, TEXT STORAGE AND 
RETRIEVAL, used GPATH$ for a typical situation in which the full 
pathname of an open file unit is quite useful. 
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Access Control Lists 

(ACLs) 



This chapter discusses: 

• Subroutines used to manipulate ACLs 

• How programs should parse an ACL 

• Typical questions and answers about ACLs 

The reader should be familiar with Access Control Lists (ACLs), as 
described in the Prime User's Guide. 



Note 

Beginning at PRIMOS Rev. 21, the System Administrator can 
enable device ACLs. While device ACLs are enabled, an 
authorized user can create user access lists for individual 
devices, granting either USE or NONE rights. The device ACLs 
facility and its commands are described in the System 
Administrator ' s Guide , Volume III: System Access and Security, 
and in the Prime User's Guide. 



SUBROUTINES THAT MANIPULATE ACLS 

Subroutines that manipulate ACLs are fully described in Volume II of 
the Subroutines Reference Guide. They are summarized briefly here. 
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When using these subroutines, you may wish to think of access 
categories as file system objects that have specific ACLs set on them. 
An access category centralizes access for several files and directories 
in one ACL represented by that access category. In a sense, the access 
category itself is a placeholder file system object with a specific ACL 
set on it. Envisioning access categories in this fashion is 
particularly useful when using subroutines such as AC$SET, AC$CHG, and 
AC$LST. 



Setting Access on Files and Directories 

You can set any of the following three accesses: 

• Default 

• Specific 

• Category 



Setting Default Access : To set access for a file or directory to the 
default access, use the AC$DFT subroutine. The default access for a 
file system object comes from the ACL for the parent directory of that 
object. You cannot set the MFD for a disk partition to default access. 
Figure 7-1 illustrates the calling sequence for the AC$DFT subroutine. 



Setting Specific Access : To set a specific ACL on a file or directory, 
use the AC$SET subroutine. Your program provides a structure 
describing the desired access. Figure 7-2 illustrates the calling 
sequence of the AC$SET subroutine. 



Setting Category Access : To set a category ACL on a file or directory, 
use the AC$CAT subroutine. Your program passes the name of the access 
category that is to protect the object. The access category must 
already exist in the same directory as the object being protected. 
Figure 7-3 illustrates the calling sequence of the AC$CAT subroutine. 



Creating Access Categories 

To create an access category, use the AC$SET subroutine. Your program 
passes the name of the access category to be created and provides a 
structure describing the desired access. Figure 7-2 illustrates the 
calling sequence of the ACS SET subroutine. 
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Protect Object With Default ACL 



Pathname of 
Target Object 



< =128 
STRING 



AC$DFT (name, code) 



HALF 
INT 



Standard 
-Error 
Code 



Calling Sequence of AC$DFT 
Figure 7-1 
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Create or Replace Specific ACL of Object, or 
Replace ACL of Access Category 



Pointer to 
ACL Structure" 



Pathname of 
Target Object" 




HALF < = 188 
INT STRING 



PTR STRTJC 



I i I 

AC$SET (key, name, addr(acl struc), code) 



Halfword 
oct dec 

00 



1 1 

2 2 



Version Number of Structure (2) 



Number of Access Pairs 



Access Pair Number 1 

(< = 80 STRING) 



122 82 
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Access Pair Number 2 

( < = 80 STRING) 



HALF 
INT 



Standard 
• Error 
Code 



Side Effects: May reset current attach point. 



Calling Sequence of AC$SET 
Figure 7-2 
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Protect Object With Access Category 



Pathname of 
Object to Be - 
Protected 



Access Category Name 
(Must Be in Same Directory 
as target Object) 



t ? 

< = 128 < = 32 
STRING STRING 

1 1 
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HALF 
INT 



Standard 
•Error 
Code 



Side Effects: May reset current attach point. 



Calling Sequence of AC$CAT 
Figure 7-3 
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Changing Access to a File System Object 

When changing access to a file system object, the object must already 
be protected by a specific ACL or a category ACL. To change the 
contents of an access category, you treat the access category as a file 
system object protected by a specific ACL. 



Changing Access for a Specific-protected Object : To change the ACL of 
an existing file system object protected by a specific ACL, including 
an access category, use either the AC$CHG or AC$SET subroutine, 
depending on the nature of the change. To modify the contents of an 
existing ACL, use AC$CHG. To replace the existing ACL with an entirely 
new ACL, use AC$SET. In both cases, your program provides a structure 
describing the desired access. 

Figure 7-4 illustrates the calling sequence of the AC$CHG subroutine. 
The calling sequence of the AC$SET subroutine is illustrated in Figure 
7-2. 



Changing Access for a Category-protected Object : If you wish to change 
the access of a file or directory that is protected by an access 
category, you have two choices: 

• Change the ACL of the access category 

• Set a new specific ACL on the file or directory 

When changing the ACL of an access category, keep in mind that the 
access for all files and directories protected by the access category 
also changes. To change the ACL of an access category, treat the 
access category as a file system object protected by a specific ACL, as 
described earlier in this section. 

To set a new specific ACL on a file or directory that is currently 
protected by a category ACL, use the AC$LIK subroutine. This creates a 
specific ACL that protects the file or directory in the same way as the 
category ACL. Now, use AC$SET or AC$CHG on the file or directory to 
change the specific ACL for the object. 

Figure 7-5 illustrates the calling sequence of the AC$LTK subroutine. 



Setting the Access for an Object to That of Another Object 

To set the access for an object to that of another object, use the 
at!$ t.tk subroutine. The access for the target object is copied from the 
ACL protecting the model object, whether via default, specific, or 
category access. A specific ACL with this access is then set on the 
target object by AC$LIK. The target and model objects need not reside 
in the same lower-level directory, as the ACL is copied by value, 
rather than by reference. 
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Change Protection of Object (Specifically Protected), or 
Change Access Control List of Access Category 
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ACL Structure" 
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Side Effects: May reset current attach point. 



Calling Sequence of AC$CHG 
Figure 7-4 
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Protect Object With Specific ACL According to 
ACL That Protects Reference Object 



Pathname of 
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Side Effects: May reset current attach point. 



Calling Sequence of AC$LIK 
f IGUKE 7-5 
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ACCESS CONTROL LISTS (ACLS) 



Figure 7-5 illustrates the calling sequence of the ACSLIK subroutine. 



Reading the Access for an Object 

To read the ACL protecting a file system object, use the AC$LST 
subroutine. Your program provides a structure describing the ACL that 
is to be filled in by AC$LST. Your program then analy2es the returned 
structure to determine the access. Figure 7-6 illustrates the calling 
sequence of the AC$LST subroutine. 



HOW PROGRAMS SHOULD PARSE AN ACL 

This section describes how to parse an ACL on an existing file system 
object. The access string information also applies to constructing an 
ACL to be placed on a file system object. 

When the AC$LST subroutine is used to read an ACL, a list of access 
pairs is returned. Each access pair has the following format: 



id: access 



Both id and access are at least one character long, separated by a 
colon~XO. If you are constructing an ACL to be passed to AC$CHG, 
access may be the null string to indicate deletion of the access pair 
for the specified id . 

The id portion of the access pair is either a user-id, a group name, or 
the character string $REST. A group name begins with a period (.), 
whereas a user-id does not. 

The access portion of the access pair can be the character string NONE, 
indicating no access rights, a character string listing individual 
access rights, or the string ALL, indicating all access rights 
(OFDALURWX at Rev. 21). Note that AC$LST will never return a string 
representing all of the supported access rights; it will be translated 
to ALL. Because ALL may represent a different set of rights at 
different revs, it is recommended that access rights be checked 
individually using the GALAC$ subroutine. CAIAC$ takes a list of 
accesses you supply as input and checks against them. CALAC$ is 
described in the Subroutines Guide , Volume II. 

You may design your program so that it ignores unrecognized characters. 
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Retrieve Access Information for Specified Object 



Version Number of Structure (2) 



Pointer to ACL Structure: 
May be NULL ( ) if — 
max_^pairs is (Zero) 



Pathname of 
Target Object" 



< =128 
STRING 



PTR STRUC 



Maximum Number of Access Pairs to Be Returned 

in acl struc ; means return no acl struc 

information, but still return acl name and acLtype 



HALF 
INT 



AC$LST (name, addr(acl_ 



i 

struc), max pairs, acl name, acl_type, code) 

J J I 



Halfword 


oct dec 








1 


1 


2 


2 


1 


1 


122 82 


123 83 



STRUC 



I 



< =128 
STRING 



HALF 
INT 



HALF 
INT 



Version Number of Structure (2) 



Number of Access Pairs Returned 



Access Pair Number 1 

( < = 80 STRING) 



Access Pair Number 2 

( < = 80 STRING) 




Standard 
^Error 
Code 



0: Protected by Specific ACL 
1 : Protected by Access Category 
2: Default From Specific ACL 
3: Default From Access Category 
4: Target Is an Access Category 



Pathname of Object That Protects 
Target Object: 

acl type acl name 




1 
2 



Pathname of Target Object 
Pathname of Access Category 
Pathname of Ancestral 
Directory With Specific ACL 
Pathname of Access Category 
Protecting Ancestral Directory 

Pathname of Target Object 



Side Effects: May reset current attach point. 



Calling Sequence of AC$LST 
Figure 7-6 
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QUESTIONS AND ANSWERS ABOUT AGLs 

This section answers some typical questions about AGLs. 

• Can ACL operations result in disk-full or quota-exceeded errors? 

Yes. Even though specific AGLs do not appear as separate files, they 
do take up room on the disk when they are created or modified. 
Therefore, it is possible to exoeed the capacity of the directory or 
the disk when: 

- Placing a specific ACL on an object that does not already have 
one 

- Creating a new access category 

- Updating the specific ACL of an object 

- Updating the ACL of an existing access category 

Changing the protection of an object from one category ACL to another 
(existing) category ACL never results in a disk-full or quota-exceeded 
error. 



• Is there a limit to how many access pairs can be put in a specific 
ACL or access category? 

Yes, there are two distinct limitations on access control lists: 

- Limit on the number of access pairs passed in acl_struc 

- Limit on the maximum size of a physical ACL on the disk 

The first limit is the maximum number of access pairs accepted by 
FRIM3S ACS subroutines. This limit, named max_acl_entries , is 
currently 32. If your program attempts to pass more than 32 access 
pairs to a subroutine such as AC$SET and AC$CHG, the subroutine returns 
the error code e$bpar (Bad parameter) to your program. (The ACSLST 
subroutine places no limit on the max__pairs argument, because it never 
returns more than 32 access pairs.l 

The second limit is more complex. The limit on the number of halfwords 
that a physical representation of an ACL may take up on the disk is a 
PRIMOS parameter named max_ent_len, which is currently 255. An ACL 
with no access pairs (not counting the $REST access pair, which is 
present in every ACL, even when not specified) takes up a minimum 
number of halfwords; named base_entry len , this value is currently 11. 
Finally, each access pair in an ACL (excluding the $REST access pair) 
takes up 5 halfwords plus the number of halfwords needed to contain the 
id portion of the access pair (not counting trailing blanks). 
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Therefore, at Rev. 19.4, the second limit can be defined as follows: 

11 + [for each access pair, (5 + (length(id(n))+l)/2)] <= 255 

If the second limit is exceeded, the AC$ subroutine called by your 
program returns the error code e$acbg (ACL too big) to your program, 
and does not perform the requested operation. 
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This chapter first describes how to read the attributes of a file 
system object; then it describes how to set each attribute. Finally, 
a quest ion-and-answer section is provided. 



HOW TO READ THE FILE ATTRIBUTES OF AN OBJECT 

To read the file attributes of a specific file system object, your 
program first opens the parent directory of that object for reading. 
See Chapter 6, DATA STORAGE AND RETRIEVAL, for a description of how to 
open a directory for reading. 

Then, your program calls the ENT$RD subroutine to read the attributes. 
Remember that your program should close the parent directory when 
finished with it. Figure 8-1 illustrates the calling sequence of 
ENTSRD. Chapter 6, DATA STORAGE AND RETRIEVAL, describes DIR$RD, a 
similar subroutine that is used to scan a directory sequentially for 
entries and read their attributes. 

The structure returned by the ENT$RD subroutine ( dirjentry ) contains 
the objectname, the file type of the object, and all other attributes 
of the object. The format of this structure is shown in Figure 8-2. 
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Read Particular Named Entry in File Directory 



Name of 
Object 



File Unit 
of Directory" 



HALF < = 32 
INT STRING 



Pointer to 
Structure 



Length of Structure 
(Currently 31) 



♦ 

PTR 



HALF 
INT 



ENT$RD (unit, name, addr(dir_entry), dir_entry__len, code) 



STRUC 



Object Name, Type, 
and Attributes 



HALF 
INT 



Standard 
Error 
Code 

(E$BFTS Implies 
Success, but More 
Info Available) 



Side Effects: Repositions unit. 



Calling Sequence of ENT$RD 
Figure 8-1 
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Halfword 
Offset Bit # 
oct dec 1 2 




1 



1 



20 16 

21 17 

22 18 

23 19 

24 20 

25 21 

26 22 

27 23 

30 24 

31 25 

32 26 

33 27 

34 28 

35 29 

36 30 



10 11 12 13 14 15 16 



directory entry type: 3 for access 
category; 2 for other objects 



length of structure (halfwords) 
- currently 31 



name of object, 32 characters, blank-padded 



has 
own 
acl 



long 

rat 

header 



reserved bits 

I I 



( A acl) owner rights 

delete/ 



truncate. 



write read 



dumped 
bit 



PRIMOS 

II 
modified 



reserved bits 



_L 



special 
file 



read/write 
lock 

I 



reserved 
bits 



year last modified minus 1900 



(acl) 

delete- 

protected 



reserved bits 

_J I L 



(Aacl) non-owner rights 

delete/ 

truncate wnte read 



reserved bits 

_l I i_ 



file type 



month last modified 
(January is month 1) 



date last modified (1-31) 

I I I L_ 



time last modified (seconds since midnight divided by 4) 



logical type 



hash thread 



trunc- 
ated 



reserved bits 



year last backed-up minus 1900 

— I I I i i i 



month last backed-up 
(January is month 1) 

I I I 



date last backed-up (1-31) 

I l l i 



time last backed-up (seconds since midnight divided by 4) 



year created minus 1900 
I I I I I 



month created 
(January is month 1) 

_J I l_ 



date created (1-31) 
_l I I i 



time created (seconds since midnight divided by 4) 



year last accessed minus 1900 
_J I I I i i 



month last accessed 
(January is month 1) 

_l I l__ 



date last accessed (1-31) 
I I I I 



time last accessed (seconds since midnight divided by 4) 



Format of Directory Entry Returned by DIR$RD or ENT$RD 

Figure 8-2 
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In PL/I, the declaration of dirjantry is: 

del 1 dir_entry based, /* Logical object entry. */ 
2 ecw, /* Entry control word. */ 

3 type bit(8), /* 3 for ACAT, 2 otherwise. */ 
3 len bit(8), /* Length of structure (currently 31). */ 
2 name char(32), /* Name of object. */ 
2 pwprot_or_delprot , /* Password protection bits (for non- 

ACL dirs) or delete-protect bit (for 
ACL dirs). */ 
3 owner, /* Owner protection bits. */ 
4 reserved bit(5), 

4 delete bit(l), /* Can delete or truncate object. */ 
4 write bit(l), /* Can write object. */ 
4 read bit(l), /* Can read object. */ 
3 delete_protect bit(l), /* Delete-protected bit. */ 
3 nonowner, /* Nonowner protection bits. */ 
4 reserved bit (4), 

4 delete bit(l), /* Can delete or truncate object. */ 
4 write bit(l), /* Can write object. */ 
4 read bit(l), /* Can read object. */ 
2 non_default_acl bit(l), /* True if not protected by 

default ACL. */ 
2 reserved_l bit (15), 
2 object_lnfo, /* Information on object. */ 

3 long_rat_hdr bit(l), /* BOOT or DSKRAT file on non- 
floppy disk. */ 
3 dumped bit(l), /* True if file has been backed up. */ 
3 dosjmod bit(l), /* True if file modified under 

PRIMOS II. */ 
3 special bit(l), /* True if special file in MFD. */ 
3 rwlock bit (2), /* Read/write lock. */ 
3 reserved bit(2), 
3 type bit(8), /* Object type. */ 
2 dtm, /* Date/ time last modified. */ 
3 date, 
4 year bit(7), /* 1900 is year 0. */ 
4 month bit (4), /* January is month 1. */ 
4 day bit(5), /* The first day of the month is day 1. */ 
3 time fixed bin(15), /* Seconds since midnight divided 

by four. */ 
2 reserved_2 fixed bin, 
2 reserved_3 fixed bin, 

2 truncated bit(l), /* True if truncated by FIX_DISK. */ 
2 reserved_4 bit (15), 
2 dtbu, /* Date/time last backed-up. */ 
3 date, 
4 year bit(7), /* 1900 is year 0. */ 
4 month bit (4), /* January is month 1. */ 
4 day bit(5), /* The first day of the month is day 1. */ 
3 time fixed bin(15); /* Seconds since midnight divided 

by four. */ 
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2 dtc, /* Date/time created. */ 
3 date, 
4 year bit(7), /* 1900 is year 0. */ 
4 month bit (4), /* January is month 1. */ 
4 day bit(5), /* The first day of the month is day 1. */ 
3 time fixed bin(15); /* Seconds since midnight divided 

by four. */ 
2 dta, /* Date/time accessed. */ 
3 date, 
4 year bit(7), /* 1900 is year 0. */ 
4 month bit (4), /* January is month 1. */ 
4 day bit(5), /* The first day of the month is day 1. */ 
3 tine fixed bin(15); /* Seconds since midnight divided 

by four. */ 



Example 

Here is a sample PL/I subroutine that retrieves attributes for a file 
identified by a pathname, and displays some of the attributes: 

display_attributes : proc(name , code) ; 

del name char(128) var, /* Pathname of file. */ 
code fixed bin(15); /* Standard error code. */ 

/* Other declarations omitted. */ 

if index(name, '>')=0 

then do; /* Not a pathname, just read current directory. */ 

call srch$$(k$read+k$getu, k$curr,0, unit , type, code) ; 

if code~=0 then return; 

f ilename=name ; 

end; 
else do; /* A pathname, open parent directory. */ 

/* First, call subroutine to split pathname (name) into parent 
directory name (pathname) and final objectname (filename). */ 

call get_parent_directory(name , pathname , filename) ; 

/* Now, open parent directory for reading. */ 

chrpos(l)=0; 

chrpos(2)=length(pathname) ; 

call tsrc$$ (k$read+k$getu , (pathname) , unit , chrpos , type , 

code); 
if code"=0 then return; 
end; /* if index(name, '>')~=0 */ 

/* Now read the desired entry. */ 
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call ent$M(uBit,filenaiie,addr(dir_entiy),31,code); 
if code~=0 

then do; /* If error, close directory and return. */ 

call clo$fu(imit,i); 

return; 

/* Now close the directory and return if error. */ 

call clo$fu(unit,code); 
if code"=0 then return; 

/* Display some info on the file. */ 

select (dir_entry . object_inf o . type.) ; 

whenC'OO'M) call tnouaC'SAM file', 8); 
whenC'Ol'M) call tnoua('DAM file', 8); 
when('02'b4) call tnouaC'SAM segdir',10); 
whenC '03 't4) call tnouaC 'DAM segdir ' , 10) ; 
when('04'M) call tnoua( 'DIRECTORY' ,3); 
when('06'M) call tnoua('AGAT' ,4); 
otherwise call tnouaC 'Unrecognized type ',17); 
end; /* select Cdir_entry. object jnfo. type) */ 

call tnouaC; ' ,2); 

if non_default_acl then call tnoua('not default-protected; ',23); 

select (dirjentry . object_inf o . rwlock) ; 
when('OO'b) call tnou( ' sys ' , 3) ; 
when( '01 'b) call tnouC'EXCL' ,4); 
whenC '10'b) call tnouC'UPDT' ,4); 
whenC'll'b) call tnouC'NONE',4); 

otherwise call tnouC '????' ,4); /* Theoretically impossible, v 
end; /* select Cdir_entry.object_info. rwlock) */ 

end; /* display_attributes: proc */ 

HDW TO SET FILE ATTRIBUTES 

You use the SATR$$ subroutine to set roost file attributes. The SATR$$ 
subroutine can set attributes only on an object in the current 
directory. Therefore, you may have to include calls to AT$ and AT$HCM 
to set a file attribute for an arbitrary object. 

Note 
SATR$$ cannot work if the object is on a write-protected disk. 

Usually, SATR$$ also updates the date/time last modified Cand date/time 
last accessed, if possible) of the parent directory. Exceptions are 
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setting the dump bit and writing date/tine last modified, date/time 
backed up, and date/time last accessed. 

When calling SATR$$, your program provides: 

• The name of the file whose attributes are to be changed 

• The length of the name 

• A key that specifies the file attribute to be changed 

• The new value of the file attribute 

The SATR$$ subroutine attempts to change the specified attribute to the 
new value, and returns an error code indicating whether or not the 
operation was successful. The caller must have protect rights on the 
object's parent directory in order to write any of the attributes 
except the dumped bit. The error E$NRIT indicates that the caller 
tried to set dta or dtc without belonging to the group, .backup$. The 
error E$ATNS indicates that the object is not an entry in a hashed 
directory; the dtc and dta attributes are not supported. 

Figure 8-3 illustrates the calling sequence of SATR$$. This section 
describes the input and output parameters used when calling SATR$$, and 
then shows a sample call to SATR$$. 



The Key : Your program 
attribute to be changed, 
meanings can be one of: 



passes a key argument that specifies the file 
The values for key and their corresponding 



Keyword 


Value 


K$DMPB 


3 


K$DTA 


10 


K$DTC 


11 


K$DTIM 


2 


K$PROT 


1 



K$RWLK 



K$SDL 



Meaning 

Set the dumped bit to 1. The only way to 
reset the dumped bit to is by modifying 
the file or directory. 

Set date/ time last accessed. 

Set date/ time created. 

Set date/ time modified. 

Set password protection keys (described in 
Subroutines Reference Guide , Volume II). 

Set read/write lock. Does not close file 
units currently open to the file; any such 
file units remain open, and no error 
indication is returned. 

Set delete-protect switch. 



8-7 



Second Edition 



ADVANCED PROGRAMMER ' S GUIDE, VOLOME II: FILE SYSTEM 



Set Attribute of Object 



K$DMPB 

K$DTA* 

K$DTC* 

K$DTIM 

K$PROT 

K$RWLK 

K$SDL 



Name of 
Object 



Length of 
Object Name 
(characters) 



New Value of 
Chosen Attribute 



HALF 32^... HALF 
INT l STRING""'*MNT 



DEPENDS 

ON 

KEY 



ft t 

SATR$$ (key, name, name_len, new_value, code) 



HALF 
INT 



Standard 

Code 

Error 



*For use only by .backup$ group. 



Side Effects: Updates dtm and dta attributes of parent directory if key is not 
K$DMPB, K$DTA, or K$DTIM. 



Calling Sequence of SATR$$ 
Figure 8-3 
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Caution 



Do not use the dumped hit to implement an incremental backup 
program unless the dumped hits are set only after the backup 
copy is verified to ha readable. 



The New Value of the File Attribute : Your program supplies the new 
value of the file attribute for all keys, except for k$dmpb which 
assumes a value of 1 (meaning "object dumped"). 

The formats of the new value for each key shown above are illustrated 
in Figure 8-4. 



Note 

Prior to Rev. 19.4, the second halfword of the new attribute 
value field had to he when key was k$prot . This second 
halfword was thereby reserved for future use. As of Rev. 19.4, 
no second halfword is required, as future modifications are no 
longer planned for the k$prot key. 

Four mnemonic keys are provided for use with the k$rwlk key of SATR$$ : 

Key Meaning 

K$DFLT Default (system-wide) read/write lock; depends on 
RWLOGK directive setting in system configuration 
file. 

K$EXCL Exclusive; the file or segment directory may be open 
to several readers or to one writer, but not to both 
a reader and a writer, at the same time. 

K$UPDT Update; the file or segment directory may be open to 
several readers and one writer at the same time. 

K$NCNE None; the file may be open to several readers and 
writers at the same time. 
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K$DMPB 



N/A 



ignored 



K$DTA 



STRUC 



year last accessed minus 

1900 

I I l I I 



7 8 9 10 11 12 13 14 15 16 



month last accessed 
(January is month 1) 
_l I I 



date last accessed 

(1-31) 
J I I I- 



time last accessed (seconds since midnight divided by 4) 



K$DTC 



STRUC 



7 8 9 10 11 12 13 14 15 16 



year created minus 
1900 
J I I I L 



month created 
(January is month 1) 

__l I I 



date created 
(1-31) 
__l I L 



time created (seconds since midnight divided by 4) 



KSDTIM 



STRUC 





12 3 4 5 6 7 


8 9 10 11 


12 13 14 15 16 





year last modified minus 

1900 

I I i I I I 


month last modified 

(January is month 1) 

i i l 


date last modified 

(1-31) 

I I i I 


1 


time last modified (seconds since midnight divided by 4) 



KSPROT 



STRUC 



9 10 11 12 13 14 15 16 



must be 

J I I L 



owner 

delete/ write read 

truncate 



must be 

J I I L 



non-owner 

delete/ write read 

truncate , 



K$RWLK 



HALF 
INT 



1 


2 


3 


4 


5 


6 7 8 9 10 11 


12 


13 


14 


15 16 


must be zero 

i i -i 1 — i 1 


read/write 
lock 



1 



6 7 8 9 10 11 12 13 14 15 16 



K$SDL 



HALF 1 or LOGICAL 
INT, BIT *2 



means not delete-protected; non-zero means delete-protected 

i i i i i i i i i i i I i 1 1 



Formats of SATR$$ Attributes for Each. Key 
Figure 8-4 
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The Error Code ; An output argument, code , informs your program of the 
success or failure of the operation. If code is 0, the operation was 
entirely successful. Otherwise, code is always positive. After a call 
to SATR$$ to set a file system attribute, code may have one of many 
values. Volume of this series contains a comprehensive list of all 
standard file system error codes. Error codes specific to this 
operation are: 



Keyword Value Meaning 

E$ATNS 238 Specified attribute is not supported in the 

directory. The target object does not have 
dta or dtc fields because it is not an 
entry in a hashed directory. 

E$BPAR 6 Bad parameter. The length of the 

object name as passed by the calling program 
is less than 1 or greater than 32. 

E$NRIT 10 Insufficient access rights. The user must 

have Protect access to the parent directory 
of the object whose file attributes are 
being changed for keys other than k$sdl ; 
for k$sdl , the user must have Delete access 
to the parent directory. 

E$!NRIT may also indicate that the user 
tried to set dta or dtc without being a 
member of the group, .backup$. 

E3DIRE 14 Operation illegal on a directory. An 

attempt has been made to set the read/write 
lock for a file directory. File 
directories do not have read/write locks. 

E$IACL 150 Entry is an access category. An attempt 

has been made to set a file attribute other 
than the date/time last modified for an 
access category. See Chapter 7, ACCESS 
CONTROL LISTS (ACLS) , for information on 
access categories. 



Example : The following FORTRAN statement changes the 
Of the file MY_DATABASE to UPDT (2): 



read/write lock 



CALL SATR$$ (K$RWLK , ' MYJDATABASE ',11, K$UFDT , CODE) 
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This chapter describes: 

• The retrieval of information on disk space in use by a directory 

• How to improve quota system perf ormance 

RETRIEVING INFORMATION CM DISK SPACE IN USE 

The Q$READ subroutine is useful for finding out how much disk space is 
used in a given directory. It reports both the amount of space in use 
by the directory itself (including files and segment directories within 
that directory) and the total amount of space in use by the directory 
and all of its subdirectories. It also reports the maximum quota 
placed on that directory, but does not report information on quotas 
placed on parent directories of that directory, even though such quotas 
may restrict activity within the directory. 

You can use Q$READ to retrieve quota information on any directory 
residing on a Rev. 19.0 (or later) disk except for the MFD (Master File 
Directory). Because the MFD is the parent directory of the entire 
disk, you can use the AVAIL command to determine how much disk space is 
being used by the disk. 
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Retrieving Quota Information for a Directory 

To retrieve quota information for a specific directory, simply call 
Q$READ with the pathname of the directory. To retrieve quota 
information on the current directory, specify a null pathname. 

An important datum returned is the quota/ non-quota directory datum. If 
the directory is not a quota directory, then the date/time last updated 
information for the directory is not maintained. Instead, this 
information is set to by Q$READ. 

Figure 9-1 illustrates the calling sequence of Q$READ. Figure 9-2 
illustrates the returned array of directory quota information 
( quota_inf o ) . 



Retrieving Quota Information for the MFD 

To retrieve quota information for the MFD, your program must accumulate 
quota information for all top-level directories in the MFD and analyze 
the information. Useful information might include: 

• The total number of records in use. (Remember to count files 
and segment directories in the MFD itself, as they are not 
accounted for in any top-level directory by Q$READ. ) 

• Whether the partition is open (has at least one top-level 
directory with no quota restriction) or closed (all top-level 
directories have quotas placed on them). 

• If the partition is closed, the total of all top-level directory 
quotas (the total quota for the partition). 

• If the partition is closed, whether it is overcommitted (total 
quota greater than the partition size) or undercommitted (total 
quota less than the partition size), and by how many records. 



IMPROVING QUOTA SYSTEM PERFORMANCE 

If your system does not use disk quotas, an attempt to read quota 
information for a directory may take some tine, as the quota system 
must size all files and directories within a directory to produce the 
directory-used and total-used values. 

To speed this up, set a very large maximum quota on all top-level 
directories on all disk partitions on your system. A maximum quota of 
1000000 (one million) records suffices. This forces PRIMOS to maintain 
up-to-the-minute quota information on all directories on your system. 
As a result, using Q$READ (or the LIST_QUOTA command) potentially takes 
much less time. However, minor overhead cost is incurred when this is 
done. 
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DISK QUOTAS 



Pathname of 

Target 

Directory 



< =128 
STRING 



Length of 

q uota info 

(fullwords) 



t 

HALF 
INT 



I 1 

Q$READ (name, quota info, max entries, type, code) 

I ^ 1 



PULL 

INT 

ARRAY(6) 



HALF 
INT 



HALF 
INT 



Quota In 



0: Quota Directory 
1: Non-quota Directory 



drmation 



on Directory 



Standard 

Error 

Code 



Side Effects: May reset cache attach point. 



Calling Sequence of Q$READ 
Figure 9-1 
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Array Halfword 
Element Offset 



1 


oct dec 


2 2 
4 4 
6 6 
10 8 

12 10) 

12 10 

13 11 


Size of Disk Record in Halfwords 

(1024 for SMDs, CMDs, FMDs; 440 for Floppies) 


2 


Number of Records Used by Directory 


3 


Maximum Number of Records (Quota) 
for Non-quota Directory 


4 


Total Number of Records Used by Directory 
(# Records Used + Total # Records Used for 
All Subordinate Directories) 


5 


Reserved 


(6 


Date/Time Last Updated (0 if Non-quota) in Format: 


6 


year minus 1900 

I 1 I I ! I 


mo(1 = January) 

i i i 


date (1-31) 

i i i i 




seconds since midnight divided by 4 



Structure of Directory Quota Information 
Figure 9-2 
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You can write a program that does this using the Q$SET subroutine, 
although the user who runs the program must have Protect access to the 
MFD of the disk partition on which the program is being run. Your 
program would set high quotas on all directories that do not already 
have quotas. 

Bear in mind that a quota cannot be set on a non-quota directory that 
is in use by any user. This includes situations where a user is 
attached to a subdirectory of the non-quota directory. Therefore, it 
is best to run such programs immediately after system coldstart, or 
just before the system is shut down (but after all users are logged 
out). 
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Interprocess 

Communication via 

the File System 



The PRBK)S file system may be used to communicate between processes. 
For example, an electronic mail subsystem can use a directory as the 
mail data base, and use specific files within the directory to 
communicate between different processes of the subsystem. 

This chapter describes the general concepts involved when using the 
file system for interprocess communication. Some specific direction is 
then given for solving typical interprocess communication problems 
using the file system. 



GENERAL CONCEPTS 

For applications that require multiple processes to run simultaneously, 
some form of interprocess communication is needed. If your application 
does not require high transaction processing rates, such as more than 
one transaction per second, you might find that relying upon the PRBDS 
file system for all of your interprocess communication saves you 
development and maintenance cost. 

If your application requires more than one transaction per second, you 
can still use the file system for primary storage, but the interprocess 
communication mechanism might be more efficiently handled by a 
combination of shared data and semaphores, at the expense of increased 
development and maintenance cost. See the Subroutines Reference Guides 
for further information. 
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File and System Read/Write Looks 

For all files in your data base, you must determine the appropriate 
per-file read/write locks. All files are created with, a read/write 
lock of SYS, meaning use the system-wide read/write lock. The 
system-wide read/write lock is set by the RWLOCK configuration 
directive during system cold start. See the System Administrator's 
Guide , Vol. I for further information on the RWLOCK directive. 

Typically, the system-wide read/ write lock is 1, corresponding to a 
per-file read/write lock of EXCL (multiple readers or 1 writer). This 
is typically the most appropriate setting for data base files. 
However, you should consider the effects on your application should the 
system-wide read/write lock be 3, corresponding to a per-file 
read/write lock of UFDT (multiple readers and 1 writer), or should it 
be 0, meaning 1 reader or 1 writer. 

If your application does not operate correctly with a non-standard 
system-wide read/write lock, then you should take one of the following 
actions: 

• Document the restriction and have your application perform a 
safety check the first time it is started up after each system 
cold start. 

• Avoid the restriction by placing per-file read/write locks on 
all files in your database. 



Documenting the Restriction and Performing a Safety Check : To document 
the restriction your application places on the system-wide read/write 
lock, include a sentence in the System Requirements portion of your 
documentation that reads as follows: 



This product requires the system-wide read/write lock to be set 
to 1 for proper operation. The system-wide read/write lock is 
controlled by the RWLOCK configuration directive in your system 
configuration file (usually named OONFIG). If the RWLOCK 
directive is not present, or has an argument of 1, the 
requirement is satisfied. However, if it has an argument of 
or 3, this product will not operate properly. See the PRIMOS 
System Administrator's Guide , Vol. I for information on the 
RWLOCK configuration directive. 



In addition, it is wise to have your product perform a safety check to 
make sure the system-wide read/write lock is set to the correct value. 
This safety check can be performed in CPL, using the following CFL 
program. This program returns the system-wide read/ write lock as its 
function value. 
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&if [exists t$temp_file.t] &then delete t$temp_file.t -no_query 
&severity Serror &ignore 

open t$temp_file.t 1 40002 /* Open for write, creating it too. 
&s sev := %severity$% 
Sdf %sev% *- Sthen Sresult UNKNOWN 
Seise 8do 

open t$temp_file.t 1 40001 /* Open it again for read. 
&s sev := %severity$% 

8df %sev% = Sthen Sresult 3 /* UFDT lock. 
&else Sdo /* Could be EXCL (1) or SNGL (0). 
close t$temp_file.t /* Close the file, 
open t$temp_file.t 1 40001 /* Open for read. 
Ss sev := %severity$% 
8df %sev% "=• Sthen &result UNKNOWN 
Seise 8do 

open t$temp_file.t 1 40001 /* Again. 
Sif %sev% = Sthen 8cresult 1 

Seise Sresult 
Send 
Send 
Send 
close t$temp_file.t 
delete t$temp_file.t 
Sreturn 



If the above CPL program is entitled RWLOCK. CPL, then the following 
sequence of CPL statements verifies that the system-wide read/write 
lock is 1 or displays an error message: 

8df [r rwlock] "= 1 &then 8do 

type System-wide read/write lock <RWL0CK> not set to 1. XXZ 
type product cannot operate under these conditions. Please 
type delete the RWLOCK directive from the system configuration 
type file, then start up the XYZ application again using the 
type STARTJXYZ command. For more information, see the XfZ 
type Guide, and the PRIMOS System Administrator' 's Guide. 
8data message /* Message to supervisor terminal. 

XYZ product shutting down due to unsupported RWLOCK configuration. 
Send 
&retum 1 Smessage RWLOCK not set to 1 
Send 



Placing a Per-file Read/Write Lock on Each File : A method of 
insulating your product from the system-wide read/write lock value is 
to have your application place a per-file read/write lock on each file 
it uses. This means that each time your application creates a file, 
your application must call the SATR$$ subroutine to set the read/write 
lock of the file to the appropriate value. (See Chapter 8, FILE 
ATTRIBUTES, for information on calling SATR$$.) 
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With this method, two problems exist: 

• To set the read/write lock of a file, the user running your 
application must have Protect access to the parent directory of 
the file. 

• Although creating a new file implies that the file is open for 
writing, your application must close the file and then reopen 
the file after setting the read/write lock for it, so that the 
new read/write lock setting may take Immediate effect. If your 
application does not perform these steps in the order indicated, 
a window of time may still exist during which one process may 
open a file for reading while another process has it open for 
writing. 



Caveats on Using the File System for Interprocess Communication 

Under no circumstances should your application depend on the timing 
characteristics of the PRIMOS file system or of any other part of 
PRIMOS. If such a dependency is built in, then your application may be 
traumatized when run on different models of Prime computers or on 
different revisions of PRIMOS. Additionally, the timing 
characteristics of the file system may vary with the system load at any 
given moment. 

It is assumed that a data base used for interprocess communication 
between processes in a given subsystem is accessed only by processes 
belonging to (or operating under the auspices of) that subsystem. 
PRIMOS makes no direct attempt to distinguish processes relating to a 
subsystem from other processes. If the data base is accessed by a 
process that is outside the domain of the subsystem, the following may 
result: 

• The contents of the data base may be rendered invalid 

• Processes within the domain of the subsystem may encounter file 
system errors, such as e$fius (File in use) 

• Portions of the data base that are protected only by the 
subsystem itself, not by the PRIMOS ACL mechanism, may be read 
or written by any users when outside the domain of the subsystem 

In summary, from the point of view of a subsystem data base, all 
processes fall into two categories: 

• Cooperating processes 

• Noncooperating processes 

If cooperative processes can be identified by user-id or group name, 
then the data base can be protected by the PRIMOS ACL mechanism against 
unauthorized access. 
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However, oertain applications require the ability for any process to 
become a cooperating process when running a program that is part of the 
subsystem. For example, an electronic mail system might require that 
all users be able to send and receive mail using a command such as 
MAIL, and yet these same users must not be allowed to access crucial 
portions of the data base when not using the MAIL command. If this is 
a requirement of your subsystem, you have two choices: 

• Accept the potential consequences described earlier in this 
section 

• Use a different interprocess communication mechanism, such as 
the PRIMENET X.25 interface 



SAMPLE MODELS OF COMMUNICATION VIA FILE SYSTEM 

This section discusses several sample subsystem models, all of which 
can be implemented using the file system for interprocess 
communication. The models discussed are: 

• Multiple processes creating file-based transactions 

• Multiple competing servers accessing file-based transactions 

• Two-process transaction management 

• Multiple processes accessing a data base 



Multiple Processes Creating File-based Transactions 

Oertain applications, such as electronic mail subsystems, require the 
ability for multiple processes to create new transactions, such as 
pieces of electronic mail, to be processed by one or more server 
processes . 

It is convenient for such a subsystem to store transactions in a 
lower-level directory within the subsystem data base, where each 
transaction is stored in its own file. 

There are two requirements: 

• While a transaction file is being created, it is incomplete and 
must not be read by one of the server processes. 

• Once a transaction file is created, it must be overwritten or 
deleted by only one of the server processes. A transaction file 
must not be reused for another transaction until the original 
transaction has been serviced. 
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Preventing Premature Servicing of a Transaction : To prevent a server 
process from servicing a file-based transaction before the transaction 
has been completely written, one of two approaches can be used: 

• A central data base file, containing information on all 
outstanding transactions, can be used to indicate the status of 
each outstanding transaction. 

• A field within the transaction file can be used to indicate the 
status of the transaction. 

The status of a transaction is used to distinguish between a 
transaction being written, waiting for servicing, and being serviced. 
In both of the above situations, the process that creates a transaction 
would update the transaction status after it finished writing the 
transaction. This ordering of events would prevent the transaction 
from being considered complete if the process creating the transaction 
was aborted (such as by a force-logout) before it finished writing the 
transaction. 

A server process might be unable to open a transaction file if it is 
still in use by the process creating the transaction file. This will 
be true if the system-wide read/write lock (RWLOCK) is set to or 1. 
This inability to open a transaction file can be used by a server 
process to recognize a transaction creation in progress. See the 
System Administrator's Guide , Vol. I for a description of the RWLOCK 
configuration directive. 



Preventing Reuse of a Transaction File : To prevent inadvertent reuse 
of a transaction file that has not yet been serviced, a unique name can 
be assigned to each transaction file. When this method is used, Add 
and Use access to the lower-level directory containing the transaction 
files is the only access required for processes creating transaction 
files. 

An obvious solution to the problem of preventing inadvertent reuse of a 
transaction file is for a process to pick a filename using some 
algorithm and then check for the previous existence of a file with that 
name. This approach has two problems: 

• It is possible for process A to create a file between the point 
in time that process B tests for the existence of the file and 
the point in time that process B subsequently uses the file. If 
this happens, both prooesses will use the same transaction file. 

• If the algorithm used to pick a filename is limited to a 
sufficiently small set of possible filenames, a process could 
spend an unreasonable amount of time testing filenames 
representing existing files if enough transactions were pending. 
This would, reduce system performance at a time when performance 
needs to be at its best to process the pending transactions. 
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Multiple Competing Servers Accessing File-based Transactions 

When files in a directory represent transactions, or units of work, it 
is often desirable for one of several transaction server processes to 
read a transaction file, perform the transaction described within, and 
delete the transaction file. The sequence of events is: 

1. A server process, S, is directed to process a transaction 
represented by (and described within) a file, F. 

2. Server process S opens file F. 

3. Server process S reads the contents of file F and performs the 
corresponding transaction. 

4. Having performed the transaction, server process S now closes 
file F. 

5. Server process S deletes file F to signal the completion of the 
transaction to other server processes within the subsystem. 

This sequence of events may not result in a sufficiently robust 
interprocess communication mechanism. The sequence shown above implies 
one crucial assumption involving interprocess communication: 



Once Step 1 is in progress, no other server process will 
attempt to perform the transaction described in file F. 



If transactions are being assigned to server processes by a central 
process, this assumption can be satisfied by having the central process 
refuse to assign file F to another server process unless server process 
S is unable to complete the transaction. 

If there is no central process, then, in Step 1, server process S must 
choose transaction file F for itself, based on some search algorithm. 
The following methods of preventing other competing server processes 
from making the same choice are in common use: 

1. A central data base file is used to maintain information on the 
outstanding transactions. In this case, each transaction is 
represented by a record within the central data base file, and 
records for transactions being serviced also identify the 
server process servicing the transaction. 

2. The beginning of each transaction file contains a field that 
describes whether and by which process the transaction is being 
serviced. 

3. The transaction file is kept open while the transaction is 
being serviced, * preventing other server processes from opening 
the same transaction file. 
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Method 1 — Central Data Base : Using a central data base file to 
maintain information on transaction status has advantages and 
disadvantages. The primary advantage is that status on all 
transactions can be retrieved by reading only one file. Disadvantages 
are: 

• Access to the central file must be single-threaded, possibly 
reducing overall throughput. 

• Additional overhead is incurred whenever a transaction is 
serviced, as its entry in the central file must be updated or 
deleted to reflect this fact. 

• A premature server abort may cause the transaction status to be 
left in the "being serviced" state too long. 



Method 3 — Transaction File Status Field : Maintaini n g a status field 
at the beginning of each transaction file has several advantages: 

• Status is easily updated by the server process servicing the 
transaction represented by the file, simply by rewriting the 
transaction status field at the beginning of the file. 

• When the transaction is completed, the status need not be 
updated if the transaction file is deleted. 

However, this method has the following disadvantages: 

• The status of all transactions must be obtained by examining 
each transaction file. 

• A premature server abort may cause the transaction status to be 
left in the "being serviced" state too long. 



Method 5 — Transaction File Kept Open : The status of a transaction 
can be inferred by the state of the transaction file. If it is in use, 
that is, open for reading and writing, then it is either being created 
or being serviced. This approach has its advantages: 

• If the server process is aborted, then the act of its logging 
out closes the transaction file. This effectively implies a 
change to a "waiting for service" status, allowing other server 
processes to open and service the file. 

• The status of the file is automatically updated when the server 
process opens the file. No separate operation need be performed 
to update the status. 

This method also has its disadvantages: 

• To determine the status of all transactions, each transaction 
file must be tested to see if it is in use. 
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• Constraints on the effective read/write look of transaction 
files exist. Multiple writers must never be allowed to open the 
file, and if the file is open for writing, no other processes 
should be able to open it for reading. This implies that the 
per-file read/write lock must be either EXCL or must be SYS. If 
it is SYS, then the system-wide read/write lock (RWIOCK) must be 
or 1. See the System Administrator's Guide , Vol. I for a 
description of the RWIOCK configuration directive. 

• Between Steps 4 and 5, that is, after closing a completed 
transaction file and deleting it, another server process may 
find that it is not in use and open the file. To prevent this, 
the file access can be set so that it does not include Read or 
Write access for server processes. (Use an existing category 
ACL, with a name like TO_BEJDELETED.ACAT, for best results.) 

After the access is changed, then Step 4 can be performed 
followed by Step 5. Any attempt by another server process to 
open the transaction file between Steps 4 and 5 results in an 
insufficient access rights error. 



Two-process Transaction Management 

A subsystem that consists of two processes usually conforms to one of 
two models: 

• One process creates transaction files, the other process 
services and deletes them 

• Both processes create and service transaction files 

The first model might be a distributed transaction processing service. 
One process receives transactions from other nodes on a network and 
deposits these transactions in the data base. The other process reads 
these transactions, services them, and then deletes the transaction 
files. 

The second model might be an electronic mail gateway service. Here, 
one process services the electronic mail traffic for the local network, 
while the other process services the incoming and outgoing electronic 
mail traffic for other networks (such as a Public Data Network, or 
PEN). 

The second model can be considered a bidirectional version of the first 
model. To implement one direction of transaction communication, 
dedicate a subdirectory of your data base to this single direction. 
The process that creates transactions can use the UID$BT and UID$CH 
subroutines to determine unique filenames, and writes files with these 
names in the lower-level directory. The process that services the 
transactions can use the DIR$RD subroutine to continually scan the 
•lower-level directory for new transaction file arrivals. 
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When using this approach, the file creation process is the only process 
creating files in the lower-level directory, and the file servicing 
process is the only process servicing files in the lower-level 
directory. There is only one concern over read/ write locks in this 
case: while a transaction file is being written fcy the transaction 
file creation process, the transaction file servicing process must not 
attempt to service the transaction. This implies that the system-wide 
read/write lock is set to or 1, or that the per-file read/write lock 
is set to EXCL (using the open/set-lock/close/open sequence described 
earlier) . 

One way to avoid the read/write lock concern entirely is to use the 
per-file dumped bit to signal the readiness of a transaction file. 
When a file is created, the dumped bit is reset. After the process 
finishes creating the file, it can use SATR$$ to set the dumped bit. 
Meanwhile, the other process is using DIR$RD to scan for new 
transaction files. Because DIR$RD also returns the dumped bit for a 
file, it can avoid opening a file that has the dumped bit reset. 



Multiple Processes Accessing a Data Base 

For concurrent access to a data base, Prime offers the MIDASPLUS 
system. If you do not need the full potential of MIDASPLUS, you can 
design your own data base system that uses only the PRIMOS file system 
for concurrency management. 

This is particularly appropriate if your subsystem uses a small number 
of central data base files to manage a larger number of transaction 
files. This possibility has been discussed earlier in this chapter. 
If this is the case, you must ensure that two processes do not attempt 
to update a central file simultaneously, and that one process does not 
attempt to read a central file while it is being written. 

This implies that the system-wide read/write lock is restricted to 1, 
or that all central files in the data base have their read/write locks 
set to EXCL (multiple readers or 1 writer). 

Performing record locking within a file is not an alternative, since 
there is no reliable method of updating a field within the file from 
one value to another while preventing another process from updating the 
same field. Moreover, such an occurrence cannot be detected by either 
process. 

For example, if process P wishes to lock a record within the file, it 
might read a field in the file that indicates the record is not in use. 
It would then update this field to indicate that it is using the 
record. In the meantime, however, process § could perform the same 
sequence of operations, and both processes would then operate as if 
they had locked the record, although the field would record only one 
process as owning the record lock. 
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Therefore, it is recommended that central data base files all have 
effective read/write locks of EXCL. If, for example, you need one 
central data base file to manage pending transactions in your data 
base, and you believe that single-threading access to the central data 
base file will result in Insufficient throughput, you might consider 
using several central data base files. Here, the appropriate central 
data base file would be selected using a hash function on the 
transaction key. This approach might increase throughput. 
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Command file, 

searching directories for, 3-7 

Command functions, 2-1, 2-2 

Command level, 

search rules, 3-2 

Command Procedure Language (CPL), 
2-2 



COMMANDS, search list, 3-2, 3-7 

Commands, 2-1 

00M0$$ subroutine, 4-7 

Compilers, 

search rule support, 3-8 
searching for include files, 
3-8 

Compressed files, 5-4 

CREA$$ subroutine, 2-24, 4-7 

CREATE command, 2-24 

Creating a file, 2-26 

Creating file directories, 2-24 

Creating file system objects, 
2-24 

CREPW$ subroutine, 2-25, 4-7 

Current attach point, 1-17, 
2-13, 4-1, 4-6, 4-9, 4-13 
searching, 3-17 

Current directory, 1-17 
opening, 4-21, 4-22 

Current object position, 1-23 

Cylinders, 1-5 



DAM (Direct Access Method), 1-15 

DAM segment directory, 1-25 

Data, 1-2 
field, 1-2 
file, 1-2 
objects, 1-2 
record, 1-2 
storage, 1-2 

Data base, 6-1 
management , 6-1 
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Data file, 

extending, 6^42 
positioning in, 6-42 
reading, 6-42 
retrieval, 6^:3 
storage, 6-43 
writing, 6^42 

Date and Tiine Created (DTC) 
attribute, 1-33 

Date and Time Last Accessed (DTA) 
attribute, 1-32 

Date and Time Last Backed Up 
(DTB) attribute, 1-35 

Date and Time Last Modified (DTM) 
attribute , 1-33 

Default search rules (See System 
search rules) 

DELETE command, 2-38 

Deleting a file, 
within a segment directory, 
6-23 

Deleting file system objects, 
2-3? 

Device ACLs, 7-1 



Directory (continued) 
home file unit, 1-29 
opening file, 2-27 
origin, 1-8, 4-1 
origin file unit, 1-29 
password, 1-18 
quota, 1-39 
quota information, 9-4 
reading, 2-31 
searching, 3-7, 3-8 
searching partitions for, 3-6 
segment , 1-9 
top-level, 1-8 
working, 1-13 
writing, 2-34 

Disk, 1-5 

( See also Disk, partition) 
formatting, 1-7 
full, 7-11 
logical, 1-7 
organization, 1-5, 1-7 
physical, 1-5, 1-7 
storage, 1-2 

Disk partitions, 1-5 
as argument, 2-16 
search all, 3-16 
search named only, 3-16 
searching, 3-6, 3-21 

Disk record availability table 
(DSKRAT) , 1-7 



DIR$CR subroutine, 2-24, 6-30, 
6-32, 6-34 

DIR$LS subroutine, 2-31 

DIR$RD subroutine, 1-29, 2-31, 
6-30, 6-39 to 6^41, 8-1, 8-3 

DIR$SE subroutine, 2-31 

Direct Access Method (DAM), 1-15 



Disk-shut-down flag, 1-26 

Dumped bit, 1-38 

Dumped/ not-dumped attribute, 
1-38 

Dynamic links, 

resolving, using ENTRY$, 3-9 



Directory, 1-3 

attaching to, 1-16 
creating file, 2-25 
current, 1-17, 4-7 
current file unit, 1-29 
duplicate names, 3-21 
file, 1-8, 1-25 
home, 1-13, 1-20, 4-7, 4-9 



E 

EDAC command, 2-22 

EDTT_AOCESS command, 2-22 

End of file, 

positioning to, 5-15 
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ENT$RD subroutine, 
8-1 to 8-3 



2-31, 6-30, 



ENTRYS, 3-2, 3-9 

[hom3_dir] keyword, 3-17 
-priiaos_direct_entries keyword, 

3-17 
-static_mode_libraries keyword, 

3-16 

Entrypoint , 

searching EPF libraries for, 

3-9 
searching PRIMOS system calls 

for, 3-17 
searching static-mode libraries 

for, 3-16 

EPF (executable program format), 
1-24 

EPF libraries, 
searching, 3-9 



Error, 
e$acbg 
e$acnf 
e$atns 
e$bfts 
e$bnam 
e$bof, 
e$bpar 

5-28 
e$bunt 
e$bver 
e$dire 
e$dkfl 

6-15 
e$dtns 
e$eof , 

5-38 
e$exst 
e$fdel 
e$fius 

6-20 
e$fntf 

6-8, 
e$fnts 
e$fuiu 
e$iacl 
e$itre 
e$mxqb 

6-17 



7-12 

6-33 

8-11 

4-21, 6-41 

4-13, 4-15, 4-18, 6-9 
5-19, 5-38 

4-12, 4-15, 4-18, 
6-33, 7-11, 8-11 

5-19 

6-33 

1-25, 8-11 

5-13, 5-28, 5-39, 
6-20, 6-33 

6-34 

1-23, 5-19, 5-28, 5-36, 
6-11, 6-14, 6-28, 6-39 

6-33 

6-23 

1-35, 5-12, 5-19, 6-8, 
10-1 

4-6, 4-13, 5-13, 5-17, 
6-33 

6-20, 6-23 

5-19 

5-14, 8-11 

4-8, 5-14 

5-14, 5-28, 5-39, 6-9, 
6-21, 6-33 



Error (continued) 

e$natt, 4-3, 4-5, 4-12, 4-18, 

4-21, 4-22 

e$nfas, 4-15, 6-9, 6-34 

e$ninf, 5-14, 6-21 

e$noqd, 6-33 

e$nrit, 4-22, 5-13, 6-8, 6-20, 

6-33, 6-35, 8-11 

e$ntsd, 1-25 

e$ntud, 1-25 

e$pnac, 6-33 

e$shdn, 1-26, 4-3, 4-5 

e$suno, 6-23 

e$uius , 5—49 

e$unop, 5-19, 5-28, 5-39, 6-5, 

6-12, 6-15, 6-28, 6-39 

e$wtpr, 6-9 

ESR (See EXPAND_SEARGH_RULES) 

Executable code file, 3-17 

Executable program format (EPF), 
1-24 

EXPAND_SEARCH_RULES (ESR) CPL 
function, 3-19 

EXPAraD_SEARCH_RUIES command, 
3-2, 3-5, 3-19 
ATTACKS used as default, 3-6 
COMMANDS! used as default, 3-7 
partition names, 3-6 
pathnames, 3-7 
referencing_dir option, 3-18 



Field, 1-2 

FILSOL subroutine, 2-38, 4-7, 
5-48 

File, 4-8 

appending to, 1-23 
closing, 1-30, 5-21 
( See also Closing a file) 
creating, 1-27, 2-26 
DAM, 1-25 
data, 6-42, 6-43 
definition, 1-10 
maximum length, 5-5 
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File (continued) 

open, using search rule 

subroutine, 3-19 
opening, 2-29, 5-6 
( See also Opening file) 
pointer, 1-29 
positioning, 1-29 
reading, 2-33 
SAM, 1-25 
system, 1-10 
text , 1-10 

truncating, 1-29, 5-17 
type, 1-37 
unit number, 1-28 
user, 1-10 
writing, 2-35 

File access control, 1-16 

File access methods, 1-15 
Direct (DAM), 1-15 
Sequential (SAM), 1-15 

File attributes, 1-31, 8-1 
date and time created (DTC), 

1-33 
date and time last accessed 

(DTA) , 1-32 
date and time last backed up 

(DEB) , 1-35 
date and time last modified 

(DIM) , 1-33 
dumped/not-dumped, 1-38 
file type, 1-37 
read/ write lock, 1-35 
setting, 8-6 
special/not-special, 1-38 

File directory, 1-8 
attributes, 6-31 
creating, 2-25, 6-31 
manipulating , 6-30 
opening, 6-34 
scanning, 6-36 

File organization, 6-2 

File system, 1-1 

communicating with, 2-1 
interfaces, 2-1 
objects, 1-5 
search, 1-14 

File type attribute, 1-37 



File unit, 1-23, 2-8 

abnormal terminate, 1-30 
accessing, 1-23 
calculated access to object, 

1-26 
closing, 1-23 

current object position, 1-23 
disk-shut-down flag, 1-26 
dynamic number allocation, 

1-27 
multiple opens, 2-9 
normal terminate, 1-30 
object type, 1-25 
object-modified flag, 1-25 
open mode, 1-24 
opening, 1-23 
positioning, 1-23 
read/ write lock, 1-26 
static number allocation, 1-28 

Filename, 
expand to full pathname, 3-5 
getting pathname for, 3-2 

Fixed-length record file, 
blocking factor, 5^44, 5-45 
calculating record position, 

5^46 
end of file, 5-45 
format , 5-44 

incomplete read/ write, 5-37 
positioning, 5-31, 5-37, 5-42 
reading, 5-31 
record length, 5-44 
writing, 5-31 

writing records to open file 
unit , 5-39 

Fixed-length records, 5-4 
advantages, 5-4 

Fixed-media Disks (FMDs) , 1-5 

Formatting a disk, 1-7 

Full pathname, 
determining, 4-18 



GPAS$$ subroutine, 4-7 
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GPATH$ subroutine, 4-7, 4-18, 
4-20, 4-24, 6-43 



K 





Key, 












K$EKUP, 


5-11 










K$GLDS, 


2-37 








H 


K$CURA, 


4-19 










K$TTRT.K, 


2-39 








Home attach point, 1-16, 2-13, 


K$DFLT, 


8-9 








4-3, 4-13 


K$DMPB, 
K$DTA, 


8-7, 
8-7 


8-9 






Home directoxy, 1-16, 4-9 


K$nrc, 


8-7 








searching, 3-17 


ksdtim, 

K$EXCL, 


8-7 
8-9 








How and when objects are named, 


K$EXST, 


5-47 








1-15 


K$FKEE, 


2-32, 


6-26 








K$FULL, 


2-32, 


6-26 








K$GETU, 


5-12, 


5-48, 


5-49, 


6-5 




K$HDMA, 


4-19 








I 


KSINIA, 


4-19 










KSINIT, 


1-29, 


6-39 






nCLQDES, 3-2, 3-8 


K$MSIZ, 


2-34 








if doesn't exist, 3-8 


K$NCAM, 


5-12, 


6-22 






[referencing_dir] keyword, 


K$NDAM, 


5-11, 


6-22 






3-18 


K$NQNE, 


8-9 










K$NSAM, 


5-11, 


6-22 






Include file, 


K$NSGD, 


5-12, 


6-5, 


6-22 




searching directories for, 3-8 


K$NSGS, 
K$P0SN, 


5-12, 
5-36 


6-5, 


6-22 




Initial attach point, 2-13 


K$PREA 


5-36 








searching, 3-17 


K$PROT 


8-7, 


8-9 








K$RDWR 


5-11, 


5-48, 


6-1, 


6-18 


Initialize process, 


K$READ 


5-11, 


5-36, 


5-48 


6-4, 


search list created, 3-2 


6-18 


6-39 








search list deleted, 3-6 


K$RP0S 


5-36 








search list set, 3-11 


K$RW1K 


8-7, 


8-9 






search rule set, 3-4 


K$SDL, 


8-7 










K$SETC 


2-16, 


4-1, 


4-12, 


4-15, 


Interprocess communication, 


4-16 










caveats, 10-4 


K$SETH 


2-16, 


4-1, 


4-12, 


4-15, 


competing servers, 10-7 


4-16 










concurrent access to data base, 


K$TRNC 


5-36 








10-10 


k$updt 


8-9 








general concepts, 10-1 


K$VMR, 


5-11, 


6-18 






models, 10-5 


K$WRIT 


, 5-11, 


5-36 


5-48 


, 6-18 



read/write locks, 10-2 
transaction file, 10-5 
two-process transaction models, 
10-9 



IPC ( See Interprocess 
communication) 



LIST_AOCESS command, 1-20 

LIST_SEARCH_RULES command, 3-12 
disabled search rules, 3-15 
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Local objects, 1-5 
Login ( See Initialize process) 
Lower-level Directory, 1-9 
LSR ( See LIST_SEARCH_RULES) 

M 

MAKE command, 1-7 

Master file directory (MFD), 1-8 

MFD (master file directory), 1-8 



Opening a file, 1-26, 2-29 
file pointer, 1-29 
file unit number, 1-28 
file unit number allocation, 

1-27 
using search rules, 3-5 
within a segment directory, 
6-17 

Opening a file directory, 2-27 

Opening a file system object, 
2-27 

ORIGIN command, 2-13 

Origin directory, 1-8 
searching, 3-17 



Object, 

closing, 2-36 

creating, 1-15, 2-10 

creating file system, 2-24 

current position, 1-23 

deleting, 2-12, 2-37 

file system, 1-2, 1-5 

local, 1-5 

name, 1-11, 2-7, 4-8 

naming , 1-15 

opening, 2-11 

opening file system, 2-27 

reading, 2-11, 2-30 

remote , 1-5 

simple name, 4-8 

specifying names, 2-7 

type, 1-25 

writing, 2-12, 2-34 

Object naming conventions, 1-15 
absolute pathname, 1-12 
components , 1-11 
full pathname, 1-14 
relative pathname, 1-12 
simple pathname, 1-13 

OPEN command, 2-27 

Open mode, 1-24 



Partition ( See Disk partition) 

Password directory, 1-18 

Pathname, 1-11 
absolute, 1-12 
full, 1-14, 4-18 
partial, 3-2 
relative, 1-12 
simple , 1-13 

Performance, 
disk access, 3-3 

Permissions ( See Access Control 
Lists (ACLsTT 

PHANT$ subroutine, 4-7 

Phantoms, 

search lists of, 3-2 

PHNTM$ subroutine, 4-7 

Positioning a file, 1-29 

PRIMOS commands, 
searching for, 3-7 
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PRIMOS file system, 
elements of, 1-4 
tree structure, 1-5 

Procedure, 1-3 

PRWF$$ subroutine, 2-35, 5-2, 
5-16 to 5-18, 5-20, 5-29, 
5-31 to 5-42 



QSREAD subroutine, 9-1, 9-3 

QSSET subroutine, 9-5 

Quota, 1-39 
directory, 9-1 
MFD, 9-2 

Quota exceeded, 7-11 



Records, variable length, 5-3 

Referencing directory, 3-18 

Relative pathname, 1-12 

Remote disks, 
ATTACKS search list for, 3-6 

Remote File Access (RFA), 1-5 

Remote objects, 1-5 

RESTS $ subroutine, 4-7 

RESU$$ subroutine, 4-7 

RESUME command, 2-2 

Return codes, 2-9 

RWLOCK, 
configuration directive, 10-2 



R 



RDLIN$ subroutine, 5-2, 5-24 to 
5-26, 5-31 

Read/write lock attribute, 1-35 

Read/write locks, 1-26 
documenting, 10-2 
EXCL, 10-2 
file, 10-2 
per file, 10-3 
safety check, 10-2 
system, 10-2 
UFDT, 10-2 

Reading file system objects, 
2-30 

Record, 1-2 
date, 1-2 
logical, 1-7 
physical , 1-7 
text , 1-2 

Records, 

fixed-length, 5-4 



SAC command, 2-17 

SAM (Sequential Access Method), 
1-15 

SAM segment directory, 1-25 

SATR$$ subroutine, 2-9, 4-7, 
8-6, 8-8, 8-10, 10-3 

SAVES $ subroutine, 4-7 

Search list, 3-1 
appending to, 3-11 
creating, 3-20 
defaults, 3-2, 3-4 
deleted automatically, 3-6 
deleting, 3-20 
duplicate rules, 3-11 
initializing, 3-20 
listing all, 3-20 
naming, 3-11 
reading, 3-20 
setting, 3-2, 3-9 to 3-11, 

3-20 
user-defined, 3-3, 3-5 
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Search rule, 3-1 

adding rule to list, 3-20 

checking existence of, 3-20 

creating, 3-10 

deleting rule from list, 3-20 

disabled/enabled, 3-15 

duplicate rule, 3-11 

enabling/disabling rule, 3-20 

format , 3-21 

locator pointer, 3-5 

nonexistent object, 3-11, 3-21 

optional, 3-15 

reading, 3-20 

setting locator pointer, 3-20 

supplying at runtime, 3-18 

user-specified, 3-3, 3-5 

Search rule keywords, 3-12 
-added_disks, 3-6, 3-16 
[home_dir] , 3-17 
-insert , 3-12 
-optional, 3-15 
[ origin_dir ] , 3-17 
-primos_direct_entries, 3-17 
[ ref erencing_dir ] , 3-18 
-static_mode_libraries, 3-16 
-system, 3-13, 3-15 

Search, rule subroutines, 3-2, 
3-11, 3-12, 3-19, 3-20 
OPSR$ , 3-18 
OPSRS$ , 3-18 
SR$ENABL, 3-15 
SRSINIT, 3-11 
SR$READ, 3-12 
SR$SSR, 3-11, 3-14 

Search rules facility, 3-1 
error in search list, 3-11 
invoking, 3-2 
performance, 3-3 
process-based, 3-2 
search scope, 3-3 
search sequence, 3-2, 3-3, 

3-21 
using, 3-2, 3-3 

Search rules file, 3-1 
comments , 3-10 
creating, 3-9 
effect of changes to, 3-11 
multiple files, 3-12 
naming, 3-9 



Search rules file (continued) 
nesting, 3-12 
used to set search list, 3-11 

SEARCHJRULES* , 3-4, 3-11 

sectors, 1-5 

Segment directories, 6-2 

Segment directory, 1-9 
closing, 6-4 
deleting a file, 6-23 
ending position, 6-28 
extending, 6-14 
extending full length, 6-15 
find free entry, 6-25 
find full entry, , 6-25 
opening, 6-3 
opening a file, 6-17 
positioning in, 6-10 
reading, 2-32 
scanning, 6-25 
size, 6-15 

starting position, 6-26 
writing, 2-34 

Sequential Access Method (SAM), 
1-15 

Set search list, 3-2, 3-9 to 
3-11 
nonexistent object, 3-11 
relocating system rules, 3-14 
suppressing system rules, 3-14 
using multiple files, 3-12 

SET_AOCESS command, 2-17 

SET_SEARCH_RULES command, 3-11 
error, 3-13 
-no_system option, 3-14 
reset option, 3-11 

SGD$DL subroutine, 2-34, 2-38, 
5-18, 6-2, 6-3, 6-24, 6-25 

SGD$£X subroutine, 5-47, 5-48, 
6-2, 6-3 

SGD$OP subroutine, 5-2, 5-7, 
5-9, 5-48, 6-2, 6-3, 6-17, 
6-19, 6-22 
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SGDR$$ subroutine, 2-31, 2-34, 
6-2, 6-3, 6-12 to 6-14, 6-16, 
6-17, 6-25 to 6-29, 6-13 

SHUTDN command, 1-26, 4-5 

Simple pathname, 1-13 

SLIST command, 4-9 

Source code file, searching 
directories for, 3-18 

SPAS$$ subroutine, 4-7 

Special/not-special attribute, 
1-38 

SRCH$$ subroutine, 1-17, 2-26, 
2-27, 2-36, 2-38, 4-7, 4-8, 
4-21, 4-23, 5-2, 5-7, 5-10, 
5-15, 5-47, 5-18, 6-3, 6-4, 
6-7, 6-30, 6-34, 6-36, 6-38 

SRSFX$ subroutine, 1-17, 2-26, 
2-27, 2-36, 2-38, 4-6, 4-24, 
5-2, 5-7, 5-8, 5-17, 5-18, 
6-3, 6-4, 6-6, 6-30, 6-34, 
6-37, 6-13 

SSR ( See SET_SEARCH_RULES) 

Static-mode libraries, 3-16 

Static-mode runfile, 
searching for, 3-7 

Storage, 1-2 

Sub-UFD (See Lower-level 
Directory) 

Subdirectory (See Lower-level 
Directory) 

Subroutine, 

AC$CAT, 2-19, 7-2, 7-5 

AC$CHG, 7-2, 7-6, 7-7, 7-9 

AC$DFT, 2-17, 7-2, 7-3 

AG$LIK, 2-20, 7-8 

AC$LST, 7-2, 7-9, 7-10 

ACIRVT, 4-7 

AC$SET, 2-18, 2-21, 7-2, 7-1, 
7-6 



Subroutine (continued) 

AT$, 2-15, 4-5, 4-7, 4-8, 4-10 
AT$ABS, 2-15, 4-5, 4-7 to 4-9, 

4-11 
AT$ANY, 2-15, 4-5, 4-7, 4-8, 

4-13, 4-14 



AT$H0M, 


2-8, 2-14, 4-1, 4-6, 


4-8 




AT$CR, 


2-13, 4-1, 4-2, 4-6 


AT$REL, 


2-15, 4-6, 4-7, 4-16, 


4-17 




ATCH$$, 


4-6 


CALACS, 


7-9 


CH$M0D, 


5-17 


CLO$FN, 


2-36, 5-21, 5-23, 5-18 


CLO$FU, 


2-36, 5-21, 5-22, 


5-48, 


6-2, 6-4 


GLOSS A, 


2-37 


CNAM$$, 


4-7, 6-13 


O0MI$$, 


4-7 


COM0$$, 


4-7 


CREA$$, 


2-24, 4-7 


CREPWS, 


2-25, 4-7 


DIRSCR, 


2-24, 6-30, 6-32, 6-34 


DIR$LS, 


2-31 


DIR$RD, 


1-29, 2-31, 6-30, 6-39 


to 6-41, 8-1, 8-3 


DD3$SE, 


2-31 


ENT$RD, 


2-31, 6-30, 8-1 to 8-3 


FILSDL, 


2-38, 4-7, 5-18 


GPAS$$, 


4-7 


GPATHS, 


4-7, 4-18, 4-20, 4-24, 


6-13 




PHANT$, 


4-7 


PHNTMS, 


4-7 


PRWF$$, 


2-35, 5-2, 5-16 to 


5-18, 


5-20, 5-29, 5-31 to 


5-12 




Q$READ, 


9-1, 9-3 


Q$SET, 


9-5 


RJlTiTNS, 


5-2, 5-24 to 5-26, 


5-31 




REST$$, 


4-7 


RESU$$, 


4-7 


SATR$$, 


2-9, 4-7, 8-6, 8-8, 


8-10, 


10-3 


SAVE$$, 


4-7 


SGD$DL, 


2-34, 2-38, 5-48, 6-2, 


6-3, 


6-24, 6-25 


SGD$EX, 


5-17, 5-48, 6-2, 6-3 


SGD$0P, 


5-2, 5-7, 5-9, 5-18, 



6-2, 6-3, 6-17, 6-19, 6-22 
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Subroutine (continued) 

SGDR$$, 2-31, 2-34, 6-2, 6-3, 
6-12 to 6-14, 6-16, 6-17, 
6-25 to 6-29, 6-13 

SPAS$$ , 4-7 

SRGH$$, 1-17, 2-26, 2-27, 
2-36, 2-38, 4-7, 4-8, 4-21, 
4-23, 5-2, 5-7, 5-10, 5-15, 
5-47, 5-48, 6-3, 6-4, 6-7, 
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